Using Jahia docker images

October 8, 2024

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 developmentproduction 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:

image3.png

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.