2 Getting Started 6.0.0

(Quick Reference) # 2 Getting Started Version: 6.0.0 ## Table of Contents # 2 Getting Started ## 2.1 Installation Requirements Before installing Grails 6.0.0 you will need as a minimum a Java Development Kit (JDK) installed version 11 or above. Download the appropriate JDK for your operating system, run the installer, and then set up an environment variable called `JAVA_HOME` pointing to the location of this installation. To automate the installation of Grails we recommend SDKMAN which greatly simplifies installing and managing multiple Grails versions. On some platforms (for example macOS) the Java installation is automatically detected. However in many cases you will want to manually configure the location of Java. For example, if you’re using bash or another variant of the Bourne Shell:
    export JAVA_HOME=/Library/Java/Home
    export PATH="$PATH:$JAVA_HOME/bin"
| On Windows you would have to configure these environment variables in `My Computer/Advanced/Environment Variables`
## 2.2 Downloading and Installing The first step to getting up and running with Grails is to install the distribution. The best way to install Grails on *nix systems is with SDKMAN which greatly simplifies installing and managing multiple Grails versions. ## Install with SDKMAN To install the latest version of Grails using SDKMAN, run this on your terminal:
    sdk install grails
You can also specify a version
    sdk install grails 6.0.0
You can find more information about SDKMAN usage on the SDKMAN Docs ## Manual installation 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 ### Unix/Linux This is typically a matter of adding something like the following `export GRAILS_HOME=/path/to/grails` to your profile This can be done by adding `export PATH="$PATH:$GRAILS_HOME/bin"` to your profile ### Windows Copy the path to the bin directory inside the grails folder you have downloaded, for example,
    C:/path_to_grails/bin
Go to Environment Variables, you can typically search or run the command below, the type env and then Enter
    Start + R
Edit the Path variable on User Variables / System Variables depending on your choice. Paste the copied path in the Path Variable. If Grails is working correctly you should now be able to type `grails -version` in the terminal window and see output similar to this:
    Grails version: 6.0.0
## 2.3 Creating an Application To create a Grails application you first need to familiarize yourself with the usage of the `grails` command which is used in the following manner:
    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 Let’s now take the new project and turn it into the classic "Hello world!" example. First, change into the "helloworld" directory you just created and start the Grails interactive console:
    $ 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. In any text editor, edit the new controller — the `HelloController.groovy` file — by adding a render line. The edited file’s code should look 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! To set a context path for your application, you can add a configuration property in `grails-app/conf/application.yml`:
    server:
        servlet:
            context-path: /helloworld
With the above configuration in place the server will instead startup at the URL http://localhost:8080/helloworld/. Alternatively, you can also set the context path via the command line:
    grails> run-app -Dgrails.server.servlet.context-path=/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.
| On Windows, if you see the error "> A problem occurred starting process 'command 'C:\path\to\java.exe''", run it again with the `--stacktrace` flag. If the root error is "Caused by: java.io.IOException: CreateProcess error=206, The filename or extension is too long", add `grails { pathingJar = true }` to your `build.gradle` file. This is a known limitation with Windows.
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 Since 3.0, Grails has an interactive mode which makes command execution faster since the JVM doesn’t have to be restarted for each command. To use interactive mode simple type 'grails' from the root of any projects and use TAB completion to get a list of available commands. See the screenshot below for an example: 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 5.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
| You can always open GSP files in the HTML editor if you just want highlighting in the community edition.
To get started with Intellij IDEA and Grails 5.0 simply go to `File / Open` and point IDEA at your `build.gradle` file to import and configure the project. #### TextMate, Sublime, VIM etc. There are several excellent text editors that work nicely with Groovy and Grails. See below for references: A bundle is available for Groovy / Grails support in Textmate. A 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 choice. A package is available for use with the Atom editor. An extension is available for use with Visual Studio Code. ## 2.7 Convention over Configuration Grails uses "convention over configuration" to configure itself. This typically means that the name and location of files is used instead of explicit configuration, hence you need to familiarize yourself with the directory structure provided by Grails. 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. - The M in MVC `i18n` - Support for internationalization (i18n). `services` - The service layer. `taglib` - Tag libraries. `utils` - Grails specific utilities. `views` - Groovy Server Pages or JSON Views - The V in MVC. `src/main/scripts` - Code generation scripts. `src/main/groovy` - Supporting sources `src/test/groovy` - Unit and integration tests. ## 2.8 Running and Debugging an Application Grails applications can be run with the built in Tomcat server using the run-app command which will load a server on port 8080 by default:
    grails run-app
You can specify a different port by using the `-port` argument:
    grails run-app -port=8090
Note that it is better to start up the application in interactive mode since a container restart is much quicker:
    $ grails
    grails> run-app
    | Grails application running at http://localhost:8080 in environment: development
    grails> stop-app
    | Shutting down application...
    | Application shutdown.
    grails> run-app
    | Grails application running at http://localhost:8080 in environment: development
You can debug a grails app by simply right-clicking on the `Application.groovy` class in your IDE and choosing the appropriate action (since Grails 3). Alternatively, you can run your app with the following command and then attach a remote debugger to it.
    grails run-app --debug-jvm
More information on the run-app command can be found in the reference guide. ## 2.9 Testing an Application The `create-*` commands in Grails automatically create unit or integration tests for you within the `src/test/groovy` directory. It is of course up to you to populate these tests with valid test logic, information on which can be found in the section on Unit and integration tests. To execute tests you run the test-app command as follows:
    grails test-app
## 2.10 Deploying an Application Grails applications can be deployed in a number of different ways. 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 `testImplementation` (or `provided` if using Grails 4.x) prior to deploying to your production container in `build.gradle`:
    testImplementation "org.springframework.boot:spring-boot-starter-tomcat"
If you are building a WAR file to deploy on Tomcat 7 then in addition you will need to change the target Tomcat version in the build. Grails is built against Tomcat 8 APIs by default. To target a Tomcat 7 container, insert a line to `build.gradle` above the `dependencies { }` section:
    ext['tomcat.version'] = '7.0.59'
| Grails 5 contains dependencies that require `javax.el-api:3.0` (eg.: `datastore-gorm:7.x`, `spring-boot:2.x`) which is only supported starting from Tomcat 8.x+, based on the tomcat version table!
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
## 2.11 Supported Java EE Containers The Grails framework requires that runtime containers support Servlet 3.0 and above. By default, Grails framework applications are bundled with an embeddable Tomcat. For more information, please see the "Deployment" section of this documentation. In addition, reference the Grails Guides for tips on how to deploy Grails to various popular Cloud services. ## 2.12 Creating Artefacts Grails ships with a few convenience targets such as create-controller, create-domain-class and so on that will create controllers and different artefact types for you. NOTE: These are just for your convenience and you can just as easily use an IDE or your favourite text editor. For example to create the basis of an application you typically need a domain model:
    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 To get started quickly with Grails it is often useful to use a feature called scaffolding to generate the skeleton of an application. To do this use one of the `generate-*` commands such as generate-all, which will generate a controller (and its unit test) and the associated views:
    grails generate-all helloworld.Book
| Quick Reference (hide)