Using Jahia docker images

The jahia/jahia-ee image is used to run development, test, and production workloads. Its resource allocation depends on the use case.

Pull command	docker pull jahia/jahia-ee:8.0.3.0
Exposed port	8080 (HTTP), 7860 (TCP), 7870 (TCP)
Min/Max memory	4GB/16GB (allocated to the JVM)
vCPU requirements	4/8 vCPUs
Directory to be mounted as a volume	none

Quick start

The fastest way to run Jahia is to use the following command:

 docker run -p 8080:8080 jahia/jahia-ee:8.0.3.0

This will start Jahia Enterprise Edition, with a 30 days trial license using a local Derby instance for its database. The resulting Jahia is then available at http://localhost:8080

Alternatively, you can run Jahia Enterprise Discovery edition using the following command:

 docker run -p 8080:8080 jahia/jahia-discovery:8.0.3.0

This will start a version of Jahia Enterprise already provisioned with discovery modules and our demo site "digitall" already installed. The instance is provided with a 30 days trial license uses a local Derby instance for its database. The resulting Jahia is then available at http://localhost:8080.

Default credentials are root / root1234 (username / password).

If you are looking for more complex examples using docker-compose.yml files, you can refer to this repository that contains a diverse set of deployment scenarios (although centered around automated provisioning). More details about provisioning are available on these Academy pages.

Running Jahia containers

Although the commands listed above are convenient to get started quickly, they are not representative of the way Jahia docker containers should be used in production.

Jahia Enterprise License

A Jahia enterprise license must be available at startup to use Jahia Enterprise features. The license can either be provided via a volume bind or through an environment variable.

Volume bind

A Jahia license can be provided via volume bind to the container. This is done by placing a license file on the container's filesystem and by passing an environment variable (JAHIA_LICENSE_OPTS) indicating where this file is located in the container.

Using docker run, the license can be referenced through a volume bind:

docker run -p 8080:8080 -it [some docker options here] \
    -v /path/to/a/license.xml:/var/jahia/license.xml:ro \
    -e JAHIA_LICENSE_OPTS="-Djahia.configure.licenseFile=/var/jahia/license.xml"
    jahia/jahia-ee:8.0.3.0

Or the same approach using docker-compose:

jahia:
  image: jahia/jahia-ee:8.0.3.0
  ports:
    - 8080:8080
  volumes: 
    - /path/to/a/license.xml:/var/jahia/license.xml:ro
  environment:
    - JAHIA_LICENSE_OPTS="-Djahia.configure.licenseFile=/var/jahia/license.xml"

Note that the path used in this example /var/jahia/license.xml could be replaced by any path within the local container, for example the file could be placed in the /tmp folder, as long as JAHIA_LICENSE_OPTS points to the correct path.

Environment variable

You can also provide a license via environment variables via passing a base64 encoded string containing the license using the JAHIA_LICENSE variable

docker run -p 8080:8080 -it [some docker options here] \
    -e JAHIA_LICENSE="YOUR_LICENSE_BASE64_STRING" \
    jahia/jahia-ee:8.0.3.0

Using the base64 tool, you can encode the content on the fly using the following:

docker run -p 8080:8080 -it [some docker options here] \
    -e JAHIA_LICENSE=$(base64 /path/to/a/license.xml) \
    jahia/jahia-ee:8.0.3.0

Or the same approach using docker-compose:

jahia:
  image: jahia/jahia-ee:8.0.3.0
  ports:
    - 8080:8080
  environment:
    - JAHIA_LICENSE=${JAHIA_LICENSE}

Database schema import

When used with PostgreSQL, MariaDB, or Derby, the Database schema is automatically imported by Jahia during the first startup, and no manual action is required. Other supported database vendors (see Supported Stack) would need to be initialized prior to starting the container.

If Jahia is connected to a Database already initialized, no schema import is done.

Ports binding

The table below lists the main networks ports open inside the container and that can be bound to the host environment, the "Usage" column indicates wether these are recommended for use in production or in development (or both). This list is not exhaustive as additional or different ports can be opened via environment variables.

As always with networking, make sure to only expose to the outside world the minimum number of ports required to run your environment.

Port	Usage	Description
8000	Development	Tomcat debug port.
8080	Production, Development	Tomcat HTTP port, primary port for accessing Jahia via a web browser.
8101	Development	SSH port to connect to the Karaf console.
8443	Production, Development	Tomcat HTTPS port, to be used alongside the SSL_ENABLED environment variable.
9229	Development	Ports used to access the GraalVM Chrome debugger tool (Jahia 8.2.0.0+ only).
10001	Development	This port can be used to connect a yourkit Java profiler, to be used alongside the YOURKIT_ACTIVATED environment variable.

Environment variables

Jahia can be configured by passing environment variables to the container at startup (see the Custom configuration deployment section to learn more). This table contains the full list of environment variables supported by the Docker containers and their default values.

Database

The following environment variables handle the way Jahia interacts with its database.

Environment variable	Default	Image(s)	Description
DB_VENDOR	derby_embedded	All Jahia images	Vendor of the database Jahia will connect to. Supported values are mariadb, postgresql, derby_embedded
DB_HOST	mariadb	All Jahia images	Remote database host
DB_NAME	jahia	All Jahia images	Database name
DB_USER	jahia	All Jahia images	Username to use the database
DB_PASS	fakepassword	All Jahia images	Password to use the database
DB_PORT	depending of database	All Jahia images	Port to connect to the database
DB_URL		All Jahia images	Providing DB_URL overwrites most other DB_ environment variables when it comes to connecting to the remote database.
DS_IN_DB	true	All Jahia images	Stores the datastore in the database.
DS_PATH		All Jahia images	Path to the datastore when stored on the filesystem

Cluster & License

Environment variable	Default	Image(s)	Description
CLUSTER_ENABLED	false	jahia/jahia-ee	Enable cluster mode for Jahia Enterprise
PROCESSING_HOST		jahia/jahia-ee	If provided, the image will indefinitely wait until it can open a TCP connection on port 8080 with the provided Jahia processing server (see alive.sh)
PROCESSING_SERVER	true	All Jahia images	false for browsing container, true for processing one
JAHIA_LICENSE		jahia/jahia-ee	A base64 encoded Jahia license. The provided environment variable is then decoded and provided to Jahia at startup.

Jahia

Environment variable	Default	Image(s)	Description
RESTORE_MODULE_STATES	false	All Jahia images	Restores the modules and their states from the database at startup. Useful when spinning up Jahia on a database that is already initialized. This is reserved to advanced use cases, and we recommend not using this variable unless instructed to by our support team.
RESTORE_PERSISTED_CONFIGURATION	false	All Jahia images	Restores the configuration at startup.  This is reserved to advanced use cases, and we recommend not using this variable unless instructed to by our support team.
DATA_FOLDER	/var/jahia	All Jahia images	Previously refered to as "digital-factory-data", directory containing Jahia data.
LOGS_FOLDER	/var/log/jahia	All Jahia images	Folder containing Jahia logs
OPERATING_MODE	development	All Jahia images	Can be development, production or distantPublicationServer
MAX_UPLOAD	268435456	All Jahia images	Maximum file size upload to Jahia
JAHIA_PLUGIN	jahia	All Jahia images	This value is generated at build time, its default value is listed in the Dockerfile.
JAHIA_LICENSE		Jahia Enterprise	Jahia Enterprise license as a base64 encoded string
LOG_MAX_DAYS	5	All Jahia images	Sets container's logs retention rule
LOG_MAX_SIZE	500M	All Jahia images	Maximum size of Jahia logs
SUPER_USER_PASSWORD	root1234	All Jahia images	Jahia's root password.
EXECUTE_PROVISIONING_SCRIPT		All Jahia images	Path or URL to a provisioning script. Jahia will be parsing that file with a JSON parser by default, except if the the URL/path ends up with .yaml, in which case the YAML parser is used.
JAHIA_PROPERTIES		All Jahia images	Allow Jahia properties to be specified as a string.
SSL_ENABLED	false	All Jahia images	When set to true, Jahia will use a certificate stored in /usr/local/tomcat/conf/ssl, otherwise no certificate is present in this folder, it will create a self-signed certificate.
SSL_CERTIFICATE_PASSWD	changeit	All Jahia images	Password attached to the certificate

Development and debugging

Environment variable	Default	Image(s)	Description
YOURKIT_ACTIVATED	false	All Jahia images	Installs and enable the Yourkit Java profiler at runtime
JPDA	false	All Jahia images	Enable or disable the Java Platform Debugger Architecture.
JPDA_ADDRESS	*:8000	All Jahia images	Specify the port to be used by JPDA

Jahia configuration

The Jahia configuration usually lives in the jahia.properties and jahia.node.properties files. All the configuration entries stored in these files can be overridden by passing environment variables to the container.

For example, to initialize the Jahia configuration karaf.remoteShell.port:

1. Translate the karaf.remoteShell.port property name with its environment variable equivalent: jahia_cfg_karaf_remoteShellPort.
2. Run the Docker container by using the -e option to set an environment variable:

   docker run -p 8080:8080 -p 20101:20101 -e jahia_cfg_karaf_remoteShellPort=20101
    jahia/jahia-ee:{jahia version}

Once the containerized Jahia starts, you can see the updated configuration in Support Tools:

Java

Environment variable	Default	Image(s)	Description
MAX_RAM_PERCENTAGE	95	All Jahia images	Percentage of the system's memory to use as Tomcat's XMX (be aware that Jahia requires at least 2GB). On a typical workstation, the max RAM is the total memory of the system. If you use cgroup or k8s limits, then those limits override the overall memory limits available on the system.
MAVEN_OPTS	-Xmx256m	All Jahia images	Sets a maximum heap for maven
MAVEN_VER	${MAVEN_VER}	All Jahia images	This value is generated at build time, its default value is listed in the Dockerfile.
CATALINA_HOME	/usr/local/tomcat	All Jahia images	Root of a runtime configuration of a specific Tomcat instance. Please see this page if you want to learn more.
CATALINA_TMPDIR	/usr/local/tomcat/temp	All Jahia images	TMP folder for Tomcat
CATALINA_OPTS		All Jahia images	Used to pass JVM options for Jahia.

Jahia is using Tomcat as its base image, therefore its environment variables can be provided when starting Jahia docker containers. More details are available on this page.

Note that on top of these parameters, all jahia.properties and jahia.node.properties entries can also be configured by passing the associated environment variables.

Good practices for orchestration

Here are good practices to build a production environment with the Docker images provided by Jahia in a stateless logic.

Persisting Jahia state

Volume binding

In order to maintain data between container restarts/rebuilds you need to create a dedicated volume for the data folder. Usually you can create a volume map for /var/jahia which contains folders like karaf, db and patches.

If you don't persist data using a volume you will not be able to back it up and restore data if your container changes.

When the container is destroyed and rebuilt, with the mapping pointing to the volume, you will have Jahia start in the same state (modules, sites, etc.) as your previous container, asuming that Jahia version and environment variables remain the same.

Important note, there should be a volume map for every node because, depending on cluster sync state, the data may differ from node to node.

Mount a folder volume

Assuming there's a volume for /var/jahia, for each node, you can also mount folders that are shared by all the nodes, like /var/jahia/sources (if you provide sources for your module) or /var/jahia/patches/remote.

Note that there is a difference between docker managed volume (like the ones normally defined at the end of docker-compose.yml file) and a folder mounted volume. A folder mounted volume makes data available through your host machine. But you need to make sure that you don't mount conflicting paths, fo example mounting both /var/jahia and /var/jahia/sources to different local folders can lead to unpredictable behaviour. 

Optimize node addition

When adding a node in place of a previously existing node (which may have been destroyed for some reason), you should be able to specify the same data volume for the new node and that should reduce start up time significantly.

You can also copy/backup/restore a volume from an existing node (processing or browsing) and map that to a new container. Assuming that the new container has the same specification as the one where the data was copied from, Jahia should start up quickly in the same state. 

Keep in mind that your license configuration needs to be able to support added nodes. 

Remote debugging

The Tomcat remote debug feature can be enabled so that you can use an IDE. This allows you to place a breakpoint and inspect the application's behavior at runtime. To do so, use the following parameters at runtime:

CATALINA_OPTS=-agentlib:jdwp=transport=dt_socket,address=*:8000,server=y,suspend=n -p  8080:8080 -p  8101:8101 -p 8000:8000

Your IDE can now connect to the remote debug port 8000 of Tomcat.