Last updated by 3 years ago

Page: Quick Start, Version:35

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.

There is a Portuguese Version on this Quick Start guide.

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:
    + grails-app
       + conf                 ---> location of configuration artifacts 
           + 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 
       + 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, test, and production. All the examples that follow operate on the development environment. For more information on environments see

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"
//    loggingSql = true
  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.

See this post on how to connect to an HSQL Database using DBVisualizer (this is useful to see the schema grails automatically generates).

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. Respond to the command with "book" (lowercase is okay at this step but not later). The target will create Book.groovy in grails-appdomain under your project. You can edit it with your favorite text editor or IDE.

Note: When naming your domain classes, stay away from names that are keywords in the database server you are using for persistence (for example, on MySQL, "Group" is a keyword; Alternatives could be something like "UserGroup").

A domain class is a persistent artifact and all properties are by default persisted to the database (Go to 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"

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 = { } }

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" (with a capital B) which generates a controller called


If you get "unable to resolve class Book" errors, you may need to run
grails create-controller Book
instead of merely
grails create-controller

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.

You will need to remove or comment out the "def index = { } " as this overrides the scaffolded action.

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 an instance of the Jetty servlet engine running on port 8080. To access the list of books open up a browser and type:


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


If response times are slow during developing try increasing your maximum heap size by setting the JAVA_OPTS environment variable to something like: '-Xmx512m' - this will set the maximum heap size to 512Mb when running Grails and should result in a noticeable improvement in response times.

What's Next