OpenCms documentation
OpenCms documentation

Headless installation

OpenCms can be installed headless instead of using the installation wizard. Parameters used in the installation are provided via a config file and then a Java program sets up OpenCms. Here you'll learn how to set up OpenCms using the auto-setup.

Here are some situations when the headless installation is preferable:

  • OpenCms should be installed on a server where you cannot access the setup wizard via a browser.
  • You want to use the same configuration more than once.
  • The configuration is provided by a person other than the one installing OpenCms.
  • You want to automate the complete server setup, integrating OpenCms installation in a larger deployment process.

Before starting the headless installation, install Tomcat and deploy the opencms.war file. Make sure that OpenCms is running. If so, execute the following command:

java -classpath "$OPENCMS/WEB-INF/lib/*:$OPENCMS/WEB-INF/classes:/usr/share/tomcat9/lib/*"\
org.opencms.setup.CmsAutoSetup\
-path $CONFIG_FILE

In the command we use two variables:

  • $OPENCMS for the path to OpenCms' web-app root folder. For example, on an Ubuntu Server (14.04) with a standard Tomcat installation and OpenCms deployed as the ROOT app, the path would be /var/libs/tomcat9/webapps/ROOT/.
  • $CONFIG_FILE for the path to the configuration file used by the headless installation.
Executing the auto-setup may take some time, especially when it comes to the modules import. Wait until you get a status update from the setup program.

In the configuration file, you provide parameters for all the settings otherwise entered when running the setup wizard. In particular, you specify which components of OpenCms should be installed, how OpenCms connects to a database and how the installation is reached on your server.

The configuration file is a simple text file with key-value pairs, each on a separate line and written as

key=value

The keys that should be set are handled by the class org.opencms.setup.CmsAutoSetupProperties and are all explained in the class' JavaDoc.

Here, we only provide an example configuration file.

setup.webapp.path=/var/lib/tomcat7/webapps/opencms
setup.default.webapp=ROOT
setup.install.components=workplace,releasenotes,template3,devdemo,bootstrap

db.product=mysql
db.provider=mysql
db.create.user=root
db.create.pwd=password
db.worker.user=root
db.worker.pwd=password
db.connection.url=jdbc:mysql://localhost:3306/
db.name=db_opencms
db.create.db=true
db.create.tables=true
db.dropDb=true
db.default.tablespace=
db.index.tablespace=
db.jdbc.driver=org.gjt.mm.mysql.Driver
db.template.db=
db.temporary.tablespace=

server.url=http://ci-9-5-x
server.name=CI-9-5-X
server.ethernet.address=
server.servlet.mapping=

All configurations can be overwritten by Java system properties. The setting for setup.install.components can be overwritten by an environment variable.