Plugins You can find out about all the publicly available Grails plugins.

Apache Tomcat plugin Plugin Collection

31 votes

100% of Grails users

build "org.grails.plugins:tomcat:8.0.50"

 Documentation  Source  Issues


Makes Tomcat the servlet container for Grails at development time


This plugin makes Tomcat the default development server for Grails. To install in Grails versions before 2.3 add this to BuildConfig.groovy:

build ":tomcat:$grailsVersion"

To install in Grails 2.3 and higher, add an entry with a specific version to BuildConfig.groovy:

build ':tomcat:9.0.0.M4.1'

for Tomcat 9,

build ':tomcat:8.0.33'

for Tomcat 8, or

build ':tomcat:7.0.70'

for Tomcat 7.

No other installation of an external Tomcat distribution is required, but you can deploy your application to a standalone Tomcat server or other servlet container or application server by creating a WAR file with the `war` script.

Configuration Options

  • tomcat.deploy.username - The username of the remote Tomcat to deploy to
  • tomcat.deploy.password - The password for the remote Tomcat to deploy to
  • tomcat.deploy.url - The remote Tomcat deploy URL
  • grails.tomcat.scan.enabled - Where Servlet 3.0 annotation classpath scanning is enabled (false by default). Note that enabling this setting will require you to significantly increase your memory settings as the Servlet 3.0 scanning feature consumes a large amount of memory.
  • grails.tomcat.scan.excludes - If class path scanning is enabled, what jars to limit
  • grails.tomcat.nio - Whether to enable the Tomcat New IO connector
  • grails.tomcat.keystorePath - The path to the Tomcat keystore for HTTPS
  • grails.tomcat.keystorePassword - The password for the keystore for HTTPS
  • grails.tomcat.jvmArgs - Any JVM arguments to pass to the isolated Tomcat instance used for run-war
  • grails.tomcat.certificateFile - The path to the OpenSSL certificate file
  • grails.tomcat.certificateKeyFile - The path to the OpenSSL certificate private key file
  • grails.tomcat.certificateKeyPassword - The password for the OpenSSL certificate private key file


As of the 9.0.0.M4 release of the plugin it is possible to run your application with HTTP/2 enabled. You must use Java 8 or higher (this is a general requirement of Tomcat 9) and SSL, and because Java 8 does not support ALPN you must also use the Tomcat Native Library and APR. Much of this is configured in the plugin, but you will have to install the Tomcat Native Library binaries and add them to your LD_LIBRARY_PATH - see the documentation for more info.

In addition to configuring the Tomcat Native Library, you must create an OpenSSL certificate and private key file. The keystore that is auto-generated for you when you specify -https and do not specify the location of your own cannot be used for HTTP/2. See the OpenSSL docs for detailed information about the process. For local testing you should be able to create a self-signed certificate with

openssl req -x509 -newkey rsa:2048 -keyout private-key.pem -out cert.pem -days 365

Then add the paths to the certificate file and private key file, along with the password you used when generating them, in BuildConfig.groovy, e.g.

grails.tomcat.certificateKeyFile = '/path/to/private-key.pem'
grails.tomcat.certificateFile = '/path/to/cert.pem'
grails.tomcat.certificateKeyPassword = '...'


You can specify JNDI naming entries to be used by the embedded Tomcat in your grails-app/conf/Config.groovy file:

grails.naming.entries = ['jdbc/mydb': [
   type: "javax.sql.DataSource", //required
   auth: "Container", // optional
   description: "Data source for ...", //optional
   //properties for particular type of resource
   url: "jdbc:oracle:thin:@dbserver:1521:DBNAME",
   username: "dbuser",
   password: "secret",
   driverClassName: "oracle.jdbc.driver.OracleDriver",
   maxActive: "8", //and so on
   maxIdle: "4"

These can then be looked up by configuring an appropriate Spring bean in @grails-app/conf/[email protected]:

beans = {
  xmlns jee:""
  jee.'jndi-lookup'(id:"myDbDataSource", 'jndi-name':"java:comp/env/jdbc/mydb")

Note if you deploy to a standalone Tomcat instance then these will need to be configured in your Tomcat context.xml file as per the Tomcat documentation

Remote Deployment

The plugin features remote deployment Gant scripts. To deploy the current Grails application simply run:

grails tomcat deploy

and to undeploy run:

grails tomcat undeploy

Note you will need to configure permissions in your tomcat-users.xml directory such as:

<role rolename="manager"/>
<user username="manager" password="secret" roles="standard,manager"/>

You can then need to specify the username/password (and potentially url) in your Config.groovy file:


Tomcat 7

If you are using Tomcat 7, ensure the user has the manager-script role

<user username="manager" password="secret" roles="manager-script" />

And the configuration in Config.groovy looks like


Using jvmArgs property

In <app>/conf/BuildConfig.groovy one has to place the property as shown below:

The properties are given only for reference as an example and please do optimize as per your requirement

grails.tomcat.jvmArgs = [
   "-server", "-XX:MaxPermSize=512m", "-XX:MaxNewSize=256m", "-XX:NewSize=256m",
   "-Xms768m", "-Xmx1024m", "-XX:SurvivorRatio=128", "-XX:MaxTenuringThreshold=0",
   "-XX:+UseTLAB", "-XX:+UseConcMarkSweepGC", "-XX:+CMSClassUnloadingEnabled",
   "-XX:+CMSIncrementalMode", "-XX:-UseGCOverheadLimit", "-XX:+ExplicitGCInvokesConcurrent"]


grails {
    tomcat {
        jvmArgs = [
           "-server", "-XX:MaxPermSize=512m", "-XX:MaxNewSize=256m", "-XX:NewSize=256m",
           "-Xms768m", "-Xmx1024m", "-XX:SurvivorRatio=128", "-XX:MaxTenuringThreshold=0",
           "-XX:+UseTLAB", "-XX:+UseConcMarkSweepGC", "-XX:+CMSClassUnloadingEnabled",
           "-XX:+CMSIncrementalMode", "-XX:-UseGCOverheadLimit", "-XX:+ExplicitGCInvokesConcurrent"]