5.3.1. Fast Deployment

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 when you run/debug your application in Studio or click CUBA > Build Tasks > Deploy. Under the hood, Studio executes the deploy task that is declared for core and web modules in the build.gradle file. Before the first execution of deploy, it also runs the setupTomcat task to install and initialize the local Tomcat server. You can run these tasks outside Studio as well.

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.

Fast deployment creates the following structure in the deploy directory (only important directories and files are shown below):

deploy/
    app_home/
        app/
            conf/
            temp/
            work/
        app-core/
            conf/
            temp/
            work/
        logs/
            app.log
        local.app.properties
        logback.xml

    tomcat/
        bin/
            setenv.bat, setenv.sh
            startup.bat, startup.sh
            debug.bat, debug.sh
            shutdown.bat, shutdown.sh
        conf/
            catalina.properties
            server.xml
            logging.properties
            Catalina/
                localhost/
        lib/
            hsqldb-2.4.1.jar
        logs/
        shared/
            lib/
        webapps/
            app/
            app-core/

  • deploy/app_home - application home directory.

    • app/conf, app-core/conf - web client and the middleware applications configuration directories.

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

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

    • logs - the logs directory. The main log file of the application is app.log by default.

    • local.app.properties - a file where you can set application properties for this particular deployment.

    • logback.xml - logging configuration.

  • deploy/tomcat - local Tomcat directory.

    • bin – the directory that contains scripts 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, configuring access to JMX, parameters to connect the debugger.

        If you experience slow startup of Tomcat on Linux installed in a virtual machine (VPS), try to configure a non-blocking entropy source for JVM in setenv.sh:

        CATALINA_OPTS="$CATALINA_OPTS -Djava.security.egd=file:/dev/./urandom"

      • startup.bat, startup.sh – the scripts that start Tomcat. The server starts in a separate console window on Windows and in the background on Unix-like operating systems.

        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 the task of the build script.

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

    • conf – the directory that contains Tomcat configuration files.

      • 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.

      • logging.properties – Tomcat logging configuration.

      • 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 the 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.

    • 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 – Tomcat logs directory.

    • shared/lib – directory of libraries that are available to all deployed applications. Classes of these libraries 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.

    • 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.

The paths to Tomcat and application home can be specified in cuba.tomcat.dir and cuba.appHome properties of build.gradle, for example:

cuba {
    // ...
    tomcat {
        dir = "$project.rootDir/some_path/tomcat"
    }
    appHome = "$project.rootDir/some_path/app_home"
}