Grails Goodness — Creating a Runnable Distribution

Grails 3.1 allows us to build a runnable WAR file for our application with the package command. We can run this WAR file with Java using the -jar option. In Grails 3.0 the package command also created a JAR file that could be executed as standalone application and a distributable Zip and Tar file. Let's see how we can still create the JAR, Zip, and Tar files with Grails 3.1.

First we use the package command to create the WAR file. The file is generated in the directory build/libs. The WAR file can be run with the command java -jar sample-0.1.war if the file name of our WAR file is sample-0.1.war. It is important to run this command in the same directory as where the WAR file is, otherwise, we get an ServletException when we open the application in our web browser (javax.servlet.ServletException: Could not resolve view with name '/index' in servlet with name 'grailsDispatcherServlet').

$ grails package
:compileJava UP-TO-DATE
:compileGroovy
:findMainClass
:assetCompile
...
Finished Precompiling Assets
:buildProperties
:processResources
:classes
:compileWebappGroovyPages UP-TO-DATE
:compileGroovyPages
:war
:bootRepackage
:assemble

BUILD SUCCESSFUL

| Built application to build/libs using environment: production
$ cd build/libs
$ java -jar sample-0.1.war
Grails application running at http://localhost:8080 in environment: production

Instead of using the Grails package command, we can use the assemble task if we use Gradle: $ ./gradlew assemble

To create a runnable JAR file we only have to remove the war plugin from our Gradle build file. The package command now creates the JAR file in the directory build/libs.

$ grails package
:compileJava UP-TO-DATE
:compileGroovy
:findMainClass
:assetCompile
...
Finished Precompiling Assets
:buildProperties
:processResources
:classes
:compileWebappGroovyPages UP-TO-DATE
:compileGroovyPages
:jar
:bootRepackage
:assemble

BUILD SUCCESSFUL

| Built application to build/libs using environment: production
$ java -jar build/libs/sample-0.1.jar
Grails application running at http://localhost:8080 in environment: production

Alternatively, we can use the Gradle task assemble instead of the Grails package command.

If we want to create a distributable Zip and Tar archive we must apply the Gradle application plugin. This plugin adds the Gradle tasks distTar and distZip. These tasks create an archive with shell scripts to start our Grails application for both Windows and Unix-like operating systems and the necessary libraries to run the application. The Grails package command will use these tasks if available to create the distributable archives. We must add the application plugin to our Gradle build file and set our application main class:

// File: build.gradle
...
apply plugin: 'application'
...
// We set the name of the class
// with the main() method to start
// the application.
mainClassName = 'sample.Application'
...

Next, we invoke the package task:

$ grails package
:compileJava UP-TO-DATE
:compileGroovy
:findMainClass
:assetCompile
...
Finished Precompiling Assets
:buildProperties
:processResources
:classes
:compileWebappGroovyPages UP-TO-DATE
:compileGroovyPages
:jar
:findMainClass
:startScripts
:distTar
:distZip
:bootRepackage
:assemble

BUILD SUCCESSFUL

| Built application to build/libs using environment: production
$ ls -al build/distributions
sample-0.1.tar sample-0.1.zip
$

We can give these files to someone else, and they would only need to unpackage the file and execute the shell scripts found in the bin directory.

To let the package command generate the runnable JAR, WAR, and distributable archives we must re-apply the war plugin to our Gradle build file. Now the package command creates everything and we can choose which file(s) we want to use.