7.3.1. Fast Deployment in Tomcat

Fast deployment is used by default when developing an application, as it provides minimum time for building, installation and starting the application. This option can also be used in production.

Fast deployment is performed using the deploy task that is declared for core and web modules in the build.gradle file. Before the first execution of deploy, a local Tomcat server should be set up and initialized using the setupTomcat task.

Warning

Please make sure your environment does not contain CATALINA_HOME, CATALINA_BASE and CLASSPATH variables. They may cause problems starting Tomcat without any reflection in logs. Reboot your computer after removing the variables.

As result of fast deployment, the following structure is created in the directory that is specified by the cuba.tomcat.dir property of the build.gradle script (only important directories and files are listed below):

bin/
    setenv.bat, setenv.sh
    startup.bat, startup.sh
    debug.bat, debug.sh
    shutdown.bat, shutdown.sh

conf/
    catalina.properties
    server.xml
    logback.xml
    logging.properties
    Catalina/
        localhost/
    app/
    app-core/

lib/
    hsqldb-2.2.9.jar

logs/
    app.log

shared/
    lib/

temp/
    app/
    app-core/

webapps/
    app/
    app-core/

work/
    app/
    app-core/

  • bin – the directory that contains tools to start and stop the Tomcat server:

    • setenv.bat, setenv.sh – the scripts that set environment variables. These scripts should be used for setting JVM memory parameters, specifying a configuration file for logging, configuring access to JMX, parameters to connect the debugger.

    • startup.bat, startup.sh – the scripts that start Tomcat. The server starts in a separate console window on Windows and in background on *nix.

      To start the server in the current console window, use the following commands instead of startup.*:

      > catalina.bat run

      $ ./catalina.sh run

    • debug.bat, debug.sh – the scripts that are similar to startup.*, but start Tomcat with an ability to connect the debugger. These scripts are launched when running the start task of the build script.

    • shutdown.bat, shutdown.sh – the scripts that stop Tomcat.

  • conf – the directory that contains configuration files of Tomcat and its deployed applications.

    • catalina.properties – the Tomcat properties. To load shared libraries from the shared/lib directory (see below), this file should contain the following line:

      shared.loader=${catalina.home}/shared/lib/*.jar

    • server.xml – Tomcat configuration descriptor.

    • logback.xml – application logging configuration descriptor.

    • logging.properties – Tomcat server logging configuration descriptor.

    • Catalina/localhost – in this directory, context.xml application deployment descriptors can be placed. Descriptors located in this directory take precedence over the descriptors in the META-INF directories of the application. This approach is often convenient for production environment. For example, with this descriptor, it is possible to specify the database connection parameters that are different from those specified in the application itself.

      Server-specific deployment descriptor should have the application name and the .xml extension. So, to create this descriptor, for example, for the app-core application, copy the contents of the webapps/app-core/META-INF/context.xml file to the conf/Catalina/localhost/app-core.xml file.

    • app – web client application configuration directory.

    • app-core – middleware application configuration directory.

  • lib – directory of the libraries that are loaded by the server’s common classloader. These libraries are available for both the server and all web applications deployed in it. In particular, this directory should have JDBC drivers of the utilized databases (hsqldb-XYZ.jar, postgresql-XYZ.jar, etc.)

  • logs – application and server logs directory. The main log file of the application is app.log (see Setting up Logging in Tomcat).

  • shared/lib – directory of libraries that are available to all deployed applications. These libraries classes are loaded by the server’s special shared classloader. Its usage is configured in the conf/catalina.properties file as described above.

    The deploy task of the build script copies all libraries not listed in the jarNames parameter, i.e. not specific for the given application, into this directory.

  • temp/app, temp/app-core – web client and the middleware applications temporary directories.

  • webapps – web application directories. Each application is located in its own subdirectory in the exploded WAR format.

    The deploy task of the build script create application subdirectories with the names specified in the appName parameters and, among other things, copy the libraries listed in the jarNames parameter to the WEB-INF/lib subdirectory for each application.

  • work/app, work/app-core – web client and the middleware applications work directories.