Migrations with Docker images

November 14, 2023

Depending on your situation, Jahia migration with Docker can either be straightforward when migrating within the same family of docker containers (for example, from jahia/jahia: to jahia/jahia: or more complex when migrating between different docker containers (for example. from jahia/jahia: to jahia/jahia-ee:

Migration within the same container family

Upgrading within the same family of docker containers (jahia/jahia or jahia/jahia-ee) is a straightforward process:

  1. Stop the Jahia container or containers if you run a cluster.
  2. Start a new Jahia container in version n+1 that points to the same volume and database as the previous one.
  3. For clustered environments, once the first Jahia container has finished starting, all the others can be started at the same time.

The first container to start will upgrade the Database content.

The following sequence of operations illustrates how to start a jahia/jahia: container and upgrade it to jahia/jahia:, as long as both Jahia instances point to the same database schema.

docker run [docker options here] --name jahia8 -v [LOCAL_PATH]:/data jahia/jahia:
docker stop jahia8 && docker rm $_
docker run [docker options here] --name jahia8 -v [LOCAL_PATH]:/data jahia/jahia:

Or a similar procedure for jahia/jahia-ee

docker run [docker options here] --name jahia8 -v [LOCAL_PATH]:/var/jahia jahia/jahia-ee:
docker stop jahia8 && docker rm $_
docker run [docker options here] --name jahia8 -v [LOCAL_PATH]:/var/jahia jahia/jahia-ee:

If you are you are using jahia/jahia images (Jahia versions below, upgrading to a version other than the next immediate version is not supported. In such a case, multiple restarts are required to upgrade by several versions. This limitation does not apply to the new generation of docker images (Jahia and above).

For multi-version Jahia cluster upgrades, only the processing node needs to be restarted for each version. See the How to upgrade procedure on the Customer Center. Non-processing nodes can be started in the final version directly once the processing has been upgraded.

Migrating from jahia/jahia to jahia/jahia-ee

Migration from jahia/jahia: to jahia/jahia-ee: is more complex. Aside from requiring some changes in your container tooling to use the new environment variable, the jahia/jahia-ee family of containers introduces some changes to the Jahia filesystem, impacting volume mounts that you might have configured.

The first step in planning your migration is to review the environment variables made available with the new images. A few of the environment variables were renamed, as per the table below: 

jahia/jahia jahia/jahia-ee  Comments
MAVEN_XMX MAVEN_OPTS Note a change in format, from MAVEN_XMX=256m to MAVEN_OPTS=-Xmx256m 




CATALINA_OPTS Can be used to pass JVM options, 3 variables were grouped into one

Once you are familiar with the environment variable, start an environment using the jahia/jahia-ee images and identify how your existing containerization environment configuration should be adjusted for these new images.

One of the biggest changes you will need to account for during the migration is the relocation of Jahia data, which moved from /data/digital-factory-data to /var/jahia.

The command below provides an example of a command that can be used to perform the migration. It assumes "bundles-deployed", "repository" and "info" folders were previously mounted and will copy these files during startup to the new /var/jahia location (also mounted).

docker run --rm -it -u 0 \
    -v ${PWD##*/}_bundles-deployed:/data/digital-factory-data/bundles-deployed \
    -v ${PWD##*/}_repository:/data/digital-factory-data/repository \
    -v ${PWD##*/}_info:/data/digital-factory-data/info \
    -v ${PWD##*/}_jahia-data:/var/jahia \
    jahia/jahia-ee: \
    sh -c "cp -a /data/digital-factory-data/* /var/jahia; chown -R 999:999 /var/jahia/*; ls -l /var/jahia"

This script will need to be adapted to your deployment scenario but should provide a good starting point to understand the migration path. 

Do not hesitate to reach out to our support team who will be able to help validate your configuration and provide you with recommendations prior to your migration.