Quick Start

The following makes it simple to start a grails project.  There's also a screencast that follows these steps for creating a small app. 

Create a Grails project

Once you have installed Grails you can use the built-in target for creating new projects:

grails create-app

The target will prompt you for the name of your project and create the project structure below:

%PROJECT_HOME%
    + grails-app
       + conf                 ---> location of configuration artifacts like data sources
           + hibernate              ---> optional hibernate config
           + spring                 ---> optional spring config
       + controllers          ---> location of controller artifacts
       + domain               ---> location of domain classes
       + i18n                 ---> location of message bundles for i18n
       + services             ---> location of services
       + taglib               ---> location of tag libraries
       + util                 ---> location of special utility classes (e.g., codecs, etc.)
       + views                ---> location of views
           + layouts              ---> location of layouts
   + lib
   + scripts                  ---> scripts
   + src
       + groovy               ---> optional; location for Groovy source files
                                   (of types other than those in grails-app/*)
       + java                 ---> optional; location for Java source files
   + test                     ---> generated test classes
   + web-app
       + WEB-INF

Configure a Data Source (Optional)

The "create-app" target created a Grails data source artifact for you in the "<..>/grails-app/conf" directory called DataSource.groovy with closures for each of the standard environments: Development, TestData, and Production. All the examples that follow operate on the development environment. For more information on environments see Configuration#environments.

By default, each data source is configured with an in-memory HSQLDB database (great for testing, but probably not that useful for live deployment) so this step is optional:

dataSource {
  pooled = false
  driverClassName = "org.hsqldb.jdbcDriver"
  username = "sa"
  password = ""
}
// environment specific settings
environments {
  development {
    dataSource {
      dbCreate = "create-drop" // one of 'create', 'create-drop','update'
      url = "jdbc:hsqldb:mem:devDB"
    }
  }
  test {
    dataSource {
      dbCreate = "update"
      url = "jdbc:hsqldb:mem:testDb"
    }
  }
  production {
    dataSource {
      dbCreate = "update"
      url = "jdbc:hsqldb:file:prodDb;shutdown=true"
    }
  }
}

Configuring the data source is a simple matter of changing the values for the desired database and driver and placing the driver jar file in the <..>/lib directory. Properties set in the dataSource node are inherited by the children.

Create a Domain Class

Make sure you are in the root directory of your project (for argument sake "my-project") by typing

cd my-project

grails create-domain-class

The target will prompt you for the name of your domain class. A domain class is a persistent artifact and all properties are by default persisted to the database (Go the the section on GORM (Grails Object Relational Mapping) for more info):

class Book {
    String title
    String author
}

At this point you may want to create some test data. An easy way to do this is to build and save the domain objects in the "init" closure of the Grails application bootstrap class found in "<..>/grails-app/conf/BootStrap.groovy" (Note: with version 0.5.6, and perhaps others, it seems this file has been changed to ApplicationBootStrap.groovy with the class declaration also changed to "class ApplicationBootStrap"):

class BootStrap {    def init = { servletContext ->
        // Create some test data
        new Book(author:"Stephen King",title:"The Shining").save()
        new Book(author:"James Patterson",title:"Along Came a Spider").save()
    }
    def destroy = {
    }
}

(Note that you can build and save domain objects here the same as in controllers or other parts of Grails applications; see Grails Object Relational Mapping (GORM) for more on domain objects.)

Create a controller

Controllers are central to Grails applications they handle web requests and URLs of the request map to a controller class and a closure within the class.

Run the "grails create-controller" target and type in the name of the controller. In our example we type "Book" which generates a controller called {{grails-app/controllers/BookController.groovy}}. Open up this controller and change it as follows to use dynamic Scaffolding which dynamically generates your application at runtime:

class BookController {
     def scaffold = Book
}

Make sure that you typed "Book" with a capital B.

NOTE: You will need to remove or comment out the "def index = { } " from the generated file for the scaffolding to work. 

Alternatively, you could also have run "grails generate-all", which creates all the scaffolding for you, and left the generated controller alone, instead of replacing it with the default scaffolding.  It might be worth learning from.

Start Grails

To start your Grails app run the following target

grails run-app

This will startup in instance of the Jetty servlet engine running on port 8080. In order to start in on a different port like e.g. 9090 use {{grails -Dserver.port=9090 run-app}}. To access the list of books open up a browser and type:

http://localhost:8080/my-project/book/list

Or, as the "list" closure is the default action for the BookController you can type:

http://localhost:8080/my-project/book

{tip:title=Speedy Grails} Grails can seem very slow in development mode, with pages taking more than a second to load. If this applies to you, then try increasing the maximum heap size by setting the {{JAVA_OPTS}} environment variable to something like this: '-Xmx512m' - this will set the maximum heap size to 512Mb when running Grails and should result in a noticeable improvement in response times. {tip}