Many modern web frameworks in the Java space are more complicated than needed and don’t embrace the Don’t Repeat Yourself (DRY) principles.

Dynamic frameworks like Rails and Django helped pave the way to a more modern way of thinking about web applications. Grails builds on these concepts and dramatically reduces the complexity of building web applications on the Java platform. What makes it different, however, is that it does so by building on already established Java technologies like Spring and Hibernate.

Grails is a full stack framework and attempts to solve as many pieces of the web development puzzle through the core technology and its associated plugins. Included out the box are things like:

All of these are made easy to use through the power of the Groovy language and the extensive use of Domain Specific Languages (DSLs)

This documentation will take you through getting started with Grails and building web applications with the Grails framework.

In addition to this documentation there are comprehensive guides that walk you through various aspects of the technology.

Finally, Grails is far more than just a web framework and is made up of various sub-projects. The following table summarizes some other key projects in the eco-system with links to documentation.

This section covers all the new features introduced in Grails 6

Grails 6.2.3-SNAPSHOT ships with the following dependency upgrades:

Before installing Grails you will need a Java Development Kit (JDK) installed with the minimum version denoted in the table below. 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:

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.

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:

Run create-app to create an application:

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

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.

The Grails Forge Command-line Interface (CLI) offers an interactive mode, which you can access by entering "grails" in your Terminal application or Linux Command Line.

Once you’re in the command-line interface, you can enhance your efficiency by utilizing the TAB key for auto-completion. For instance:

This interactive mode provides a convenient way to explore available Grails commands and options, making your Grails development workflow more efficient and user-friendly.

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

Because Grails is built upon the Spring Framework (Spring Boot), the Gradle build tool, and the Groovy programming language, it is possible to develop Grails application using most popular JVM Integrated Development Environments (IDEs). Some IDEs offer more specialized support for Grails, while others may offer basic support for managing dependencies/plugins, running Gradle tasks, code-completion and syntax highlighting.

Grails adopts the "convention over configuration" approach to configure itself. In this approach, the name and location of files are used instead of explicit configuration. Therefore, it’s essential to become familiar with the directory structure provided by Grails. Here’s a breakdown of the key directories and links to relevant sections:

Understanding this directory structure and its conventions is fundamental to efficient Grails development.

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:

You can specify a different port by using the -port argument:

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

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.

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

Via Gradle, Grails applications can be executed using the built-in application server using the bootRun command. By default, it launches a server on port 8080:

To specify a different port, you can set the system property -Dgrails.server.port as follows:

For debugging a Grails app, you have two options. You can either right-click on the Application.groovy class in your IDE and select the appropriate debugging action, or you can run the app with the following command and then connect a remote debugger to it:

For more information on the bootRun command, please refer to the bootRun section of the Grails reference guide.

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:

Gradle offers a convenient feature where you can automatically generate unit and integration tests for your application using the create-* commands. These generated tests are stored in the src/test/groovy and src/integration-test/groovy directories. However, it is your responsibility to populate these tests with the appropriate test logic. You can find comprehensive guidance on crafting valid test logic in the section dedicated to Unit and Integration Tests.

To initiate the execution of your tests, including both unit and integration tests, you can utilize the Gradle check task. Follow these steps:

Remember, testing is not just a process; it’s a fundamental practice that enhances your Grails application’s reliability. Viewing test reports helps you analyze and understand the test results, making it easier to identify and address any issues.

By following these testing practices and reviewing test reports, you can deliver a high-quality Grails application to your users with confidence.

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:

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:

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:

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:

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:

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:

Via Gradle, Grails applications offer multiple deployment options.

For traditional container deployments, such as Tomcat or Jetty, you can generate a Web Application Archive (WAR) file using the Gradle war task as follows:

This task generates a WAR file with a -plain suffix within the build/libs directory, ready for deployment according to your container’s guidelines.

By default, the war task runs in the production environment. You can specify a different environment, such as development, by overriding it in the Gradle command:

If you prefer not to use a separate Servlet container, you can create and run the Grails WAR file as a regular Java application:

When deploying Grails, ensure that your container’s JVM runs with the -server option and sufficient memory allocation. Here are recommended VM flags:

The Grails framework requires that runtime containers support Servlet 3.0 and above. By default, Grails framework applications are bundled with an embedded Tomcat server. For more information, please see the Deployment section of this documentation.

In addition, read the Grails Guides for tips on how to deploy Grails to various popular Cloud services.

Grails provides a set of useful CLI commands for various tasks, including the creation of essential artifacts such as controllers and domain classes. These commands simplify the development process, although you can achieve similar results using your preferred Integrated Development Environment (IDE) or text editor.

For instance, to create the foundation of an application, you typically need to generate a domain model using Grails Commands:

Executing these commands will result in the creation of a domain class located at grails-app/domain/myapp/Book.groovy, as shown in the following code:

The Grails CLI offers numerous other commands that you can explore in the Grails command line reference guide.

It may seem odd that in a framework that embraces "convention-over-configuration" that we tackle this topic now. With Grails' default settings you can actually develop an application without doing any configuration whatsoever, as the quick start demonstrates, but it’s important to learn where and how to override the conventions when you need to. Later sections of the user guide will mention what configuration settings you can use, but not how to set them. The assumption is that you have at least read the first section of this chapter!

Configuration in Grails is generally split across 2 areas: build configuration and runtime configuration.

Build configuration is generally done via Gradle and the build.gradle file. Runtime configuration is by default specified in YAML in the grails-app/conf/application.yml file.

If you prefer to use Grails 2.0-style Groovy configuration then it is possible to specify configuration using Groovy’s ConfigSlurper syntax. Two Groovy configuration files are available: grails-app/conf/application.groovy and grails-app/conf/runtime.groovy:

For Groovy configuration the following variables are available to the configuration script:

For example:

The application.yml file was introduced in Grails 3.0, and YAML is now the preferred format for configuration files.

Grails has a set of core settings that are worth knowing about. Their defaults are suitable for most projects, but it’s important to understand what they do because you may need one or more of them later.

Since Grails 3.0, logging is handled by the Logback logging framework and can be configured with the grails-app/conf/logback.xml file.

For more information on configuring logging refer to the Logback documentation on the subject.

Grails artifacts (controllers, services …​) get injected a log property automatically.

Prior to Grails 3.3.0, the name of the logger for Grails Artifact followed the convention grails.app.<type>.<className>, where type is the type of the artifact, for example, controllers or services, and className is the fully qualified name of the artifact.

Grails 3.3.x simplifies logger names. The next examples illustrate the changes:

BookController.groovy located at grails-app/controllers/com/company NOT annotated with @Slf4j

BookController.groovy located at grails-app/controllers/com/company annotated with @Slf4j

BookService.groovy located at grails-app/services/com/company NOT annotated with @Slf4j

BookService.groovy located at grails-app/services/com/company annotated with @Slf4j

BookDetail.groovy located at src/main/groovy/com/company annotated with @Slf4j

When Grails logs a stacktrace, the log message may include the names and values of all of the request parameters for the current request. To mask out the values of secure request parameters, specify the parameter names in the grails.exceptionresolver.params.exclude config property:

Request parameter logging may be turned off altogether by setting the grails.exceptionresolver.logRequestParameters config property to false. The default value is true when the application is running in DEVELOPMENT mode and false for all other environments.

If you set the configuration property logging.config, you can instruct Logback to use an external configuration file.

Alternatively, you can supply the configuration file location with a system property:

$ ./gradlew -Dlogging.config=/Users/me/config/logback.groovy bootRun

Or, you could use an environment variable:

Grails provides the following GORM configuration options:

For example, to enable failOnError for all domain classes:

and to enable failOnError for domain classes by package:

To setup Grails to use an HTTP proxy there are two steps. Firstly you need to configure the grails CLI to be aware of the proxy if you wish to use it to create applications and so on. This can be done using the GRAILS_OPTS environment variable, for example on Unix systems:

For Windows systems the environment variable can be configured under My Computer/Advanced/Environment Variables.

With this configuration in place the grails command can connect and authenticate via a proxy.

Secondly, since Grails uses Gradle as the build system, you need to configure Gradle to authenticate via the proxy. For instructions on how to do this see the Gradle user guide section on the topic.

Every new Grails application features an Application class within the grails-app/init directory.

The Application class subclasses the GrailsAutoConfiguration class and features a static void main method, meaning it can be run as a regular application.

There are several ways to execute the Application class, if you are using an IDE then you can simply right click on the class and run it directly from your IDE which will start your Grails application.

This is also useful for debugging since you can debug directly from the IDE without having to connect a remote debugger when using the run-app --debug-jvm or ./gradlew bootRun --debug-jvm command from the command line.

You can also package your application into a runnable WAR file, for example:

This is useful if you plan to deploy your application using a container-less approach.

There are several ways in which you can customize the Application class.

The Application class also implements the GrailsApplicationLifeCycle interface which all plugins implement.

This means that the Application class can be used to perform the same functions as a plugin. You can override the regular plugins hooks such as doWithSpring, doWithApplicationContext and so on by overriding the appropriate method:

Since Grails is built on Java technology setting up a data source requires some knowledge of JDBC (the technology that stands for Java Database Connectivity).

If you use a database other than H2 you need a JDBC driver. For example for MySQL you would need Connector/J.

Drivers typically come in the form of a JAR archive. It’s best to use the dependency resolution to resolve the jar if it’s available in a Maven repository, for example you could add a dependency for the MySQL driver like this:

Once you have the JAR resolved you need to get familiar with how Grails manages its database configuration. The configuration can be maintained in either grails-app/conf/application.groovy or grails-app/conf/application.yml. These files contain the dataSource definition which includes the following settings:

A typical configuration for MySQL in application.groovy may be something like:

Example of advanced configuration using extra properties:

The previous example configuration assumes you want the same config for all environments: production, test, development etc.

Grails' DataSource definition is "environment aware", however, so you can do:

The dbCreate property of the DataSource definition is important as it dictates what Grails should do at runtime with regards to automatically generating the database tables from GORM classes. The options are described in the DataSource section:

In development mode dbCreate is by default set to "create-drop", but at some point in development (and certainly once you go to production) you’ll need to stop dropping and re-creating the database every time you start up your server.

It’s tempting to switch to update so you retain existing data and only update the schema when your code changes, but Hibernate’s update support is very conservative. It won’t make any changes that could result in data loss, and doesn’t detect renamed columns or tables, so you’ll be left with the old one and will also have the new one.

Grails supports migrations with Liquibase or Flyway via plugins.

The actual dataSource bean is wrapped in a transaction-aware proxy so you will be given the connection that’s being used by the current transaction or Hibernate Session if one is active.

If this were not the case, then retrieving a connection from the dataSource would be a new connection, and you wouldn’t be able to see changes that haven’t been committed yet (assuming you have a sensible transaction isolation setting, e.g. READ_COMMITTED or better).

The H2 database console is a convenient feature of H2 that provides a web-based interface to any database that you have a JDBC driver for, and it’s very useful to view the database you’re developing against. It’s especially useful when running against an in-memory database.

You can access the console by navigating to http://localhost:8080/h2-console in a browser. See the Spring Boot H2 Console Documentation for more information on the options available.

By default all domain classes share a single DataSource and a single database, but you have the option to partition your domain classes into two or more data sources.

Dependency resolution is handled by the Gradle build tool, all dependencies are defined in the build.gradle file. Refer to the Gradle user guide for more information.

Grails 3.0’s command line system differs greatly from previous versions of Grails and features APIs for invoking Gradle for build related tasks, as well as performing code generation.

When you type:

Grails searches the profile repository based on the profile of the current application. If the profile is for a web application then commands are read from the web profile and the base profile which it inherits from.

Since command behavior is profile specific the web profile may provide different behavior for the run-app command then say a profile for running batch applications.

When you type the following command:

It will first search the application, and then the profile for commands:

To get a list of all commands and some help about the available commands type:

which outputs usage instructions and the list of commands Grails is aware of:

Interactive mode is a feature of the Grails command line which keeps the JVM running and allows for quicker execution of commands. To activate interactive mode type 'grails' at the command line and then use TAB completion to get a list of commands:

If you need to open a file whilst within interactive mode you can use the open command which will TAB complete file paths:

Even better, the open command understands the logical aliases 'test-report' and 'dep-report', which will open the most recent test and dependency reports respectively. In other words, to open the test report in a browser simply execute open test-report. You can even open multiple files at once: open test-report test/unit/MyTests.groovy will open the HTML test report in your browser and the MyTests.groovy source file in your text editor.

TAB completion also works for class names after the create-* commands:

If you need to run an external process whilst interactive mode is running you can do so by starting the command with a !:

Note that with ! (bang) commands, you get file path auto completion - ideal for external commands that operate on the file system such as 'ls', 'cat', 'git', etc.

To exit interactive mode enter the exit command. Note that if the Grails application has been run with run-app normally it will terminate when the interactive mode console exits because the JVM will be terminated. An exception to this would be if the application were running in forked mode which means the application is running in a different JVM. In that case the application will be left running after the interactive mode console terminates. If you want to exit interactive mode and stop an application that is running in forked mode, use the quit command. The quit command will stop the running application and then close interactive mode.

With Grails Forge, when you execute the grails command without any arguments, the Grails Command Line Interface (CLI) enters interactive mode. In this mode, it functions like a shell, allowing you to run multiple CLI commands without the need to re-initialize the CLI runtime. This mode is particularly useful when working with code-generation commands (such as create-controller), creating multiple projects, or exploring various CLI features.

One of the advantages of interactive mode is the availability of tab-completion. You can simply press the TAB key to view possible options for a given command or flag. Here’s an example of the available options in interactive mode:

You can create your own Command scripts by running the create-script command from the root of your project. For example the following command will create a script called src/main/scripts/hello-world.groovy:

See below for an example script that prints "Hello World":

The description method is used to define the output seen by grails help and to aid users of the script. The following is a more complete example of providing a description taken from the generate-all command:

As you can see this description profiles usage instructions, a flag and an argument. This allows the command to be used as follows:

You can create your own commands by running the create-command command from the root of your project. For example the following command will create a command called grails-app/commands/HelloWorldCommand:

Since Grails 3.2.0, commands have similar abilities as scripts in regards to retrieving arguments, template generation, file access, and model building.

If you created a command in a previous version of grails, you can update your command to have those abilities by changing which trait you are implementing.

Commands created in Grails 3.1.x or lower implement the ApplicationCommand trait by default which requires your command to implement the following method:

Commands created in Grails 3.2.0 or higher implement the GrailsApplicationCommand trait by default which requires your command to implement the following method:

Custom commands can be executed using grails run-command:

Commands can also be executed using the runCommand gradle task. Note that the gradle task uses camelCase:

If the grails server is a subproject (e.g., in a project created with the angular profile), the subproject command can still be invoked from the gradle wrapper in the parent project:

With Gradle, a custom command is a piece of functionality that you can add to your Grails application and execute via the command-line interface (CLI). These commands are not part of the core Grails framework but are extensions you can create to perform specific tasks or operations that are unique to your application’s requirements. Custom commands are a powerful way to automate various tasks, interact with your application, and perform administrative functions from the command line. When you run custom commands, they cause the Grails environment to start, giving you full access to the application context and the runtime, allowing you to work with the application’s resources, services, and configuration as needed within your custom command.

There are several reasons why you might want to write a custom command for your Grails application:

In Grails, you can create custom commands by implementing the GrailsApplicationCommand trait. By default, this trait requires your command to implement the handle() method as following:

Here’s a step-by-step guide on how to create custom commands using the GrailsApplicationCommand trait with examples, and how to run these commands.

In Grails, you can create custom commands by implementing the GrailsApplicationCommand trait. Custom commands allow you to add functionality to your Grails application that can be executed via the command-line interface (CLI). Here’s a step-by-step guide on how to create custom commands using the GrailsApplicationCommand trait with examples, and how to run these commands.

Step 1: Create a Custom Command

To create a custom command, you need to create a Groovy class that implements the GrailsApplicationCommand trait. This trait provides methods for command execution. Let’s create a simple example command that greets the user:

In this example, we’ve created a GreetCommand class that implements the GrailsApplicationCommand trait. It provides a getName() method to define the command name, a getDescription() method for a brief description, and the run() method to specify the code to execute when the command is run.

Step 2: Build Your Grails Application

Before you can use the runCommand task, ensure you have built your Grails application using the following command:

This command will compile your application and make it ready for running custom commands.

Step 3: Run the Custom Command

To run the custom command, use Gradle’s runCommand task. Open your terminal and navigate to your Grails application’s root directory. Then, run the custom command with the following Gradle command:

In the command above, replace "greet" with the name of your custom command. This will execute the GreetCommand, and you will see the output.

Here’s the expected final output when you run the greet command:

Additional Features: Command Arguments and Options

Grails also supports command-line arguments and options for custom commands. You can define these in your command class by implementing the GrailsApplicationCommand interface. Here’s an example of a command that takes a name as an argument and an optional --loud option to make the greeting louder:

Now you can run the greet command with arguments and options:

This allows you to create more versatile and interactive custom commands for your Grails application.

In summary, creating custom commands in Grails using the GrailsApplicationCommand trait is a powerful way to extend your application’s functionality beyond the web interface. You can define the command’s name, description, and logic, and then execute it from the command line, optionally passing arguments and options as needed.

Using the executionContext in the Grails Custom Commands

In Grails, the executionContext is a runtime context object that provides valuable information about the current execution environment of a Grails application. It includes details such as the application’s environment (e.g., development, production, test) and allows developers to access this context within custom commands.

Custom commands in Grails can use the executionContext to make informed decisions and perform specific tasks based on the current runtime environment. For example, developers can write conditional logic in custom commands that execute differently in production, development, or testing environments. This flexibility enables custom commands to adapt and behave differently depending on the context in which they are run, making them versatile tools for managing and extending Grails applications.

Suppose you have a Grails application that manages customer data, and you want to create a custom command to perform data backup. In this scenario, you may want the backup process to behave differently depending on whether you’re running it in a development, staging, or production environment.

Here’s an example of how you can create a custom command that uses the executionContext to determine the backup behavior:

In this example:

When you run this custom command using ./gradlew runCommand -Pargs="backup", it will adapt its behavior based on whether you’re in a production or non-production environment, demonstrating how the executionContext can be used to make environment-specific decisions in a realistic scenario.

How to Create a Custom Command from a Grails Plugin

You can create custom commands not only within your Grails application but also from a Grails plugin. Here’s how to do it:

By following these steps, you can create and run custom commands from a Grails plugin, extending the functionality of your Grails application as needed. This approach allows you to modularize your custom functionality and share it across multiple Grails projects if necessary.

Creating a project is the primary usage of the CLI. The primary command for creating a new project is create-app, which creates a standard Grails web application that communicates over HTTP. For other types of application, see the documentation below.

| Flag | Description | Example

Grails ships with a lot of command line functionality out of the box that you may find useful in your own scripts (See the command line reference in the reference guide for info on all the commands).

Any script you create can invoke another Grails script simply by invoking a method:

The above will invoke the test-app command. You can also pass arguments using the method arguments:

Since Grails 3.1 the Gradle Build System is used for build related tasks such as compilation, runnings tests and producing binary distributions of your project. It is recommended to use Gradle 2.2 or above with Grails 3.1 (and higher).

The build is defined by the build.gradle file which specifies the version of your project, the dependencies of the project and the repositories where to find those dependencies (amongst other things).

When you invoke the grails command the version of Gradle that ships with Grails 3.1 (currently 2.9) is invoked by the grails process via the Gradle Tooling API:

You can invoke Gradle directly using the gradle command and use your own local version of Gradle, however you will need Gradle 2.2 or above to work with Grails 3.0 (and higher):

Dependencies for your project are defined in the dependencies block. In general, you can follow the Gradle documentation on dependency management to understand how to configure additional dependencies.

The default dependencies for the Grails Web application can be seen below:

Note that version numbers are not present in the majority of the dependencies. This is thanks to the dependency management plugin which configures a Maven BOM that defines the default dependency versions for certain commonly used dependencies and plugins:

As mentioned previously the grails command uses an embedded version of Gradle and certain Grails commands that existed in previous versions of Grails map onto their Gradle equivalents. The following table shows which Grails command invoke which Gradle task:

You can invoke any of these Grails commands using their Gradle equivalents if you prefer:

Note however that you will need to use a version of Gradle compatible with Grails 3.1 (Gradle 2.2 or above). If you wish to invoke a Gradle task using the version of Gradle used by Grails you can do so with the grails command:

However, it is recommended you do this via interactive mode, as it greatly speeds up execution and provides TAB completion for the available Gradle tasks:

To find out what Gradle tasks are available without using interactive mode TAB completion you can use the Gradle tasks task:

When you create a new project with the create-app command, a default build.gradle is created. The default build.gradle configures the build with a set of Gradle plugins that allow Gradle to build the Grails project:

The default plugins are as follows: * groovy - The Groovy plugin add support for Groovy projects. It can deal with Groovy code mixed with Groovy and Java. Read More: The Groovy Plugin * com.github.erdi.webdriver-binaries - A plugin that downloads and caches WebDriver binaries specific to the OS the build runs on. Read More at GitHub README * war - The The WAR plugin changes the packaging so that Gradle creates as WAR file from your application. You can comment out this plugin if you wish to create only a runnable JAR file for standalone deployment. * idea - The IDEA plugin generates files that are used by IntelliJ IDEA, thus making it possible to open the project from IDEA. Read More: The IDEA Plugin * com.bertramlabs.asset-pipeline - The asset pipeline plugin enables the compilation of static assets (JavaScript, CSS etc.) * application - The Application plugin facilitates creating an executable JVM application. Read More: The Application Plugin * eclipse - The Eclipse plugins generate files that are used by the Eclipse IDE, thus making it possible to import the project into Eclipse (File - Import…​ - Existing Projects into Workspace). Read More: The Eclipse Plugin

Many of these are built in plugins provided by Gradle or third party plugins. The Gradle plugins that Grails provides are as follows:

When you create a Grails application with the create-app command by default the "web" profile is used:

You can specify a different profile with the profile argument:

Profiles encapsulate the project commands, templates and plugins that are designed to work for a given profile. The source for the profiles can be found on Github, whilst the profiles themselves are published as JAR files to the Grails central repository.

To find out what profiles are available use the list-profiles command:

For more information on a particular profile use the profile-info command:

The idea behind creating a new profile is that you can setup a default set of commands and plugins that are tailored to a particular technology or organisation.

To create a new profile you can use the create-profile command which will create a new empty profile that extends the base profile:

The above command will create a new profile in the "mycompany" directory where the command is executed. If you start interactive mode within the directory you will get a set of commands for creating profiles:

The commands are as follows:

To customize the dependencies for your profile you can specify additional dependencies in profile.yml.

Below is an example profile.yml file:

With the above configuration in place you can publish the profile to your local repository with gradle install:

Your profile is now usable with the create-app command:

With the above command the application will be created with the "mycompany" profile which includes an additional dependency on the "myplugin" plugin and also includes the "hibernate" and "asset-pipeline" features (more on features later).

Note that if you customize the dependency coordinates of the profile (group, version etc.) then you may need to use the fully qualified coordinates to create an application:

One profile can extend one or many different parent profiles. To define profile inheritance you can modify the build.gradle of a profile and define the profile dependences. For example typically you want to extend the base profile:

By inheriting from a parent profile you get the following benefits:

To define the order of inheritance ensure that your dependencies are declared in the correct order. For example:

In the above snippet the skeleton from the "plugin" profile is copied first, followed by the "web" profile. In addition, the "web" profile overrides commands from the "plugin" profile, whilst if the dependency order was reversed the "plugin" profile would override the "web" profile.

A profile is a simple directory that contains a profile.yml file and directories containing the "commands", "skeleton" and "templates" defined by the profile. Example:

The above example is a snippet of structure of the 'web' profile. The profile.yml file is used to describe the profile and control how the build is configured.

A profile can define new commands that apply only to that profile using YAML or Groovy scripts. Below is an example of the create-controller command defined in YAML:

Commands defined in YAML must define one or many steps. Each step is a command in itself. The available step types are:

For example to invoke a Gradle task, you can define the following YAML:

If you need more flexibility than what the declarative YAML approach provides you can create Groovy script commands. Each Command script is extends from the GroovyScriptCommand class and hence has all of the methods of that class available to it.

The following is an example of the create-script command written in Groovy:

For more information on creating CLI commands see the section on creating custom scripts in the Command Line section of the user guide.

A Profile feature is a shareable set of templates and dependencies that may span multiple profiles. Typically you create a base profile that has multiple features and child profiles that inherit from the parent and hence can use the features available from the parent.

To create a feature use the create-feature command from the root directory of your profile:

This will create a myfeature/feature.yml file that looks like the following:

As a more concrete example. The following is the feature.yml file from the "asset-pipeline" feature:

The structure of a feature is as follows:

The contents of the skeleton get copied into the application tree, whilst the application.yml and build.gradle get merged with their respective counterparts in the profile by used.

With the feature.yml you can define additional dependencies. This allows users to create applications with optional features. For example:

The above example will create a new application using your new feature and the "hibernate" feature.

Domain classes are core to any business application. They hold state about business processes and hopefully also implement behavior. They are linked together through relationships; one-to-one, one-to-many, or many-to-many.

GORM is Grails' object relational mapping (ORM) implementation. Under the hood it uses Hibernate (a very popular and flexible open source ORM solution) and thanks to the dynamic nature of Groovy with its static and dynamic typing, along with the convention of Grails, there is far less configuration involved in creating Grails domain classes.

You can also write Grails domain classes in Java. See the section on Hibernate Integration for how to write domain classes in Java but still use dynamic persistent methods. Below is a preview of GORM in action:

A domain class can be created with the create-domain-class command:

This will create a class at the location grails-app/domain/myapp/Person.groovy such as the one below:

You can customize the class by adding properties:

Once you have a domain class try and manipulate it with the shell or console by typing:

This loads an interactive GUI where you can run Groovy commands with access to the Spring ApplicationContext, GORM, etc.

Try performing some basic CRUD (Create/Read/Update/Delete) operations.

For more information on using GORM see the dedicated documentation for the GORM project.

A controller handles requests and creates or prepares the response. A controller can generate the response directly or delegate to a view. To create a controller, simply create a class whose name ends with Controller in the grails-app/controllers directory (in a subdirectory if it’s in a package).

The default URL Mapping configuration ensures that the first part of your controller name is mapped to a URI and each action defined within your controller maps to URIs within the controller name URI.