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.

#Quick Start

#Create a Grails project
#Configure a Data Source (Optional)
#Create a Domain Class
#Create a controller
#Start Grails

#What's Next

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 
           + 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, 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. Responding to the command with "book" 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").
Note: Grails doesn't seem to like names like MYCar or MYtruck (more than one capital letter at the beginning of the name). Names like MyCar or MyTruck, however, seem to work fine. Classes with names that have more than one capital letter in the beginning give 404 pages even if views for the class exist or scaffolding is set. If you are having problems with views not showing up and your names have more than one capital letter in the beginning of the name, try changing your names to the "Grails-friendly" format and try again.

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 an 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}

What's Next

See Checking Projects into SVN on how to check your new grails app into source control.
Set up your grails app in your IDE
Browse the many grails plugins and install some such as webtest to create functional tests via canoo webtest.