5.1. Application Home

Application home is a file system directory where the CUBA application stores temporary files and where you can place local.app.properties and logback.xml configuration files. Most of the application directories described below are located in the application home. File storage also uses a subdirectory in the application home by default.

As CUBA application creates various files (temporary files, log files etc) in the application home, this directory should be write-accessible for the user running the application.

The framework gets the application home path from the app.home Java system property.

It is recommended that you set this property explicitly using the -D command line argument when starting application server running the application.
Specifying application home explicitly

When running UberJAR, specify -D command line argument, for example:

java -Dapp.home=/opt/app_home -jar app.jar

When using WAR deployment, set app.home using -D command line argument in an appropriate startup script or by another recommended for the application server way. For example, in Tomcat, create bin/setenv.sh script with the following content:

CATALINA_OPTS="-Dapp.home=\"$CATALINA_BASE/work/app_home\" -Xmx512m -Dfile.encoding=UTF-8"

If you are using deployment to Tomcat Windows Service, place each property on a separate line in the Java Options field of the Tomcat service settings window.

Automatic application home detection

If the app.home system property is not provided from the command line, it is set automatically according to the following rules:

  1. If the application is started as UberJAR, the current working directory becomes application home.

  2. If catalina.base system property is set (i.e. the application is working under Tomcat), the application home is set to ${catalina.base}/work/app_home.

  3. Otherwise, app home is set to the .app_home subdirectory of the user home directory.

Options 2 and 3 have the following drawback: the Logback initialization procedure comes into play before the app.home property is set, so references like ${app.home} in logback.xml won’t work and location of log files (if it is defined using such link) will be undetermined. Also, you won’t be able to override logging properties simply by adding logback.xml to the application home because it won’t be found by the initialization procedure.

When using Fast Deployment at development stage, the application home is set to the deploy/app_home directory of your project since CUBA 7.2. If your project is based on an older version of the platform, the application directories are located inside Tomcat’s conf and work subdirectories.