2 Getting Started

2.1 Installation Requirements

To automate the installation of Grails we recommend the GVM tool which greatly simplifies installing and managing multiple Grails versions.

For manual installation, we recommend the video installation guides from grailsexample.net:

• Windows
• Linux
• Mac OS X

These will show you how to install Grails too, not just the JDK.

A JDK is required in your Grails development environment. A JRE is not sufficient.

On some platforms (for example OS X) the Java installation is automatically detected. However in many cases you will want to manually configure the location of Java. For example:

export JAVA_HOME=/Library/Java/Home
export PATH="$PATH:$JAVA_HOME/bin"

if you're using bash or another variant of the Bourne Shell.

2.2 Downloading and Installing

The best way to install Grails on *nix systems is with the GVM tool which greatly simplifies installing and managing multiple Grails versions.

For manual installation follow these steps:

• Download a binary distribution of Grails and extract the resulting zip file to a location of your choice
• Set the GRAILS_HOME environment variable to the location where you extracted the zip
• On Unix/Linux based systems this is typically a matter of adding something like the following export GRAILS_HOME=/path/to/grails to your profile
• On Windows this is typically a matter of setting an environment variable under My Computer/Advanced/Environment Variables
• Then add the bin directory to your PATH variable:
• On Unix/Linux based systems this can be done by adding export PATH="$PATH:$GRAILS_HOME/bin" to your profile
• On Windows this is done by modifying the Path environment variable under My Computer/Advanced/Environment Variables

If Grails is working correctly you should now be able to type grails -version in the terminal window and see output similar to this:

bc. Grails version: 3.0.0

2.3 Creating an Application

grails [command name]

Run create-app to create an application:

grails create-app helloworld

This will create a new directory inside the current one that contains the project. Navigate to this directory in your console:

cd helloworld

2.4 A Hello World Example

$ cd helloworld
$ grails

You should see a prompt that looks like this:

What we want is a simple page that just prints the message "Hello World!" to the browser. In Grails, whenever you want a new page you just create a new controller action for it. Since we don't yet have a controller, let's create one now with the create-controller command:

grails> create-controller hello

Don't forget that in the interactive console, we have auto-completion on command names. So you can type "cre" and then press <tab> to get a list of all create-* commands. Type a few more letters of the command name and then <tab> again to finish.

The above command will create a new controller in the grails-app/controllers/helloworld directory called HelloController.groovy. Why the extra helloworld directory? Because in Java land, it's strongly recommended that all classes are placed into packages, so Grails defaults to the application name if you don't provide one. The reference page for create-controller provides more detail on this.

We now have a controller so let's add an action to generate the "Hello World!" page. The code looks like this:

package helloworld
class HelloController {
    def index() {
        render "Hello World!"
    }
}

The action is simply a method. In this particular case, it calls a special method provided by Grails to render the page.

Job done. To see your application in action, you just need to start up a server with another command called run-app:

grails> run-app

This will start an embedded server on port 8080 that hosts your application. You should now be able to access your application at the URL http://localhost:8080/ - try it!

Note that in previous versions of Grails the context path was by default the name of the application. If you wish to restore this behavior you can configure a context path in grails-app/conf/application.yml:

server:
    'contextPath': '/helloworld'

With the above configuration in place the server will instead startup at the URL http://localhost:8080/helloworld/.

If you see the error "Server failed to start for port 8080: Address already in use", then it means another server is running on that port. You can easily work around this by running your server on a different port using run-app -port=9090. '9090' is just an example: you can pretty much choose anything within the range 1024 to 49151.

The result will look something like this:

This is the Grails intro page which is rendered by the grails-app/view/index.gsp file. It detects the presence of your controllers and provides links to them. You can click on the "HelloController" link to see our custom page containing the text "Hello World!". Voila! You have your first working Grails application.

One final thing: a controller can contain many actions, each of which corresponds to a different page (ignoring AJAX at this point). Each page is accessible via a unique URL that is composed from the controller name and the action name: /<appname>/<controller>/<action>. This means you can access the Hello World page via /helloworld/hello/index, where 'hello' is the controller name (remove the 'Controller' suffix from the class name and lower-case the first letter) and 'index' is the action name. But you can also access the page via the same URL without the action name: this is because 'index' is the default action . See the end of the controllers and actions section of the user guide to find out more on default actions.

2.5 Using Interactive Mode

For more information on the capabilities of interactive mode refer to the section on Interactive Mode in the user guide.

2.6 Getting Set Up in an IDE

IntelliJ IDEA

IntelliJ IDEA is an excellent IDE for Grails 3.0 development. It comes in 2 editions, the free community edition and the paid-for ultimate edition.

The community edition can be used for most things, although GSP syntax higlighting is only part of the ultimate edition. To get started with Intellij IDEA and Grails 3.0 simply go to File / Import Project and point IDEA at your build.gradle file to import and configure the project.

Eclipse

We recommend that users of Eclipse looking to develop Grails application take a look at Groovy/Grails Tool Suite, which offers built in support for Grails including automatic classpath management, a GSP editor and quick access to Grails commands.

Like Intellij you can import a Grails 3.0 project using the Gradle project integration.

NetBeans

NetBeans provides a Groovy/Grails plugin that automatically recognizes Grails projects and provides the ability to run Grails applications in the IDE, code completion and integration with the Glassfish server. For an overview of features see the NetBeans Integration guide on the Grails website which was written by the NetBeans team.

TextMate, Sublime, VIM etc.

There are several excellent text editors that work nicely with Groovy and Grails. See below for references:

• A TextMate bundle exists Groovy / Grails support in Textmate
• A Sublime Text plugin can be installed via Sublime Package Control for the Sublime Text Editor.
• See this post for some helpful tips on how to setup VIM as your Grails editor of choise.
• An Atom Package is available for use with the Atom editor

2.7 Convention over Configuration

Here is a breakdown and links to the relevant sections:

• grails-app - top level directory for Groovy sources
• conf - Configuration sources.
• controllers - Web controllers - The C in MVC.
• domain - The application domain.
• i18n - Support for internationalization (i18n).
• services - The service layer.
• taglib - Tag libraries.
• utils - Grails specific utilities.
• views - Groovy Server Pages - The V in MVC.
• scripts - Code generation scripts.
• src/main/groovy - Supporting sources
• src/test/groovy - Unit and integration tests.

2.8 Running an Application

grails run-app

You can specify a different port by using the server.port argument:

grails -Dserver.port=8090 run-app

Note that it is better to start up the application in interactive mode since a container restart is much quicker:

$ grails
grails> run-app
| Server running. Browse to http://localhost:8080/helloworld
| Application loaded in interactive mode. Type 'stop-app' to shutdown.
| Downloading: plugins-list.xml
grails> stop-app
| Stopping Grails server
grails> run-app
| Server running. Browse to http://localhost:8080/helloworld
| Application loaded in interactive mode. Type 'stop-app' to shutdown.
| Downloading: plugins-list.xml

More information on the run-app command can be found in the reference guide.

2.9 Testing an Application

To execute tests you run the test-app command as follows:

grails test-app

2.10 Deploying an Application

If you are deploying to a traditional container (Tomcat, Jetty etc.) you can create a Web Application Archive (WAR file), and Grails includes the war command for performing this task:

grails war

This will produce a WAR file under the build/libs directory which can then be deployed as per your container's instructions.

Note that by default Grails will include an embeddable version of Tomcat inside the WAR file, this can cause problems if you deploy to a different version of Tomcat. If you don't intend to use the embedded container then you should change the scope of the Tomcat dependencies to provided prior to deploying to your production container in build.gradle:

provided "org.springframework.boot:spring-boot-starter-tomcat"

Unlike most scripts which default to the development environment unless overridden, the war command runs in the production environment by default. You can override this like any script by specifying the environment name, for example:

grails dev war

If you prefer not to operate a separate Servlet container then you can simply run the Grails WAR file as a regular Java application. Example:

grails war
java -Dgrails.env=prod -jar build/libs/mywar-0.1.war

When deploying Grails you should always run your containers JVM with the -server option and with sufficient memory allocation. A good set of VM flags would be:

-server -Xmx768M -XX:MaxPermSize=256m

2.11 Supported Java EE Containers

• Tomcat 7
• GlassFish 3 or above
• Resin 4 or above
• JBoss 6 or above
• Jetty 8 or above
• Oracle Weblogic 12c or above
• IBM WebSphere 8.0 or above

It's required to set "-Xverify:none" in "Application servers > server > Process Definition > Java Virtual Machine > Generic JVM arguments" for older versions of WebSphere. This is no longer needed for WebSphere version 8 or newer.

Some containers have bugs however, which in most cases can be worked around. A list of known deployment issues can be found on the Grails wiki.

2.12 Creating Artefacts

These are just for your convenience and you can just as easily use an IDE or your favourite text editor.

grails create-app helloworld
cd helloworld
grails create-domain-class book

This will result in the creation of a domain class at grails-app/domain/helloworld/Book.groovy such as:

package helloworld
class Book {
}

There are many such create-* commands that can be explored in the command line reference guide.

To decrease the amount of time it takes to run Grails scripts, use the interactive mode.

2.13 Generating an Application

grails generate-all helloworld.Book