Migrations with Docker images

Performing a Jahia migration with Docker is generally straightforward, but it is always recommended to review Jahia release notes and recommendations for applying the update as it might require changes in your modules.

Instructions in this document focus only on Docker operations, it assumes that any required code or configuration changes requested in the migration notes were performed.

Performing the migration

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-ee:8.1.6.1 container and upgrade it to jahia/jahia-ee:8.1.7.1, 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:8.1.6.1
docker stop jahia8 && docker rm $_
docker run [docker options here] --name jahia8 -v [LOCAL_PATH]:/data jahia/jahia:8.1.7.1

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.

Manual migration steps

Sometimes, extra work is required for specific versions. Such cases will be documented below.

Upgrading to Jahia 8.2.1.0+

This version is using a newer base image, and you will need to migrate the permissions of the data and log files of the container. This is required because newer Ubuntu images are using UID/GID 999, which we were using for the container user. You will know if you are affected by this if you get an error message on container startup:

Error! No write permission for DATA_FOLDER: /some/folder

To fix it, you need to run a few commands in the container as root. The problem is, the container will not start up because its permission check will fail. To get into the container, we need to create a copy of the container with a modified entry point:

$ docker commit CONTAINER_NAME temp_jahia_migration

Then, you would be able to start the container with a different entry point:

$ docker run -ti --entrypoint=sh -v HOST_JAHIA_FOLDER:/var/jahia -u root temp_jahia_migration

It is important to use the same volumes for the migration. The migration step changes the permission for the files inside it, so pay close attention to what volumes are you using when you start jahia, and add the same volumes to the migration container start command.

Once inside, run these commands:

# find ${DATA_FOLDER} ${LOGS_FOLDER} -user 999 -exec chown -h 9999:9999 {} +
# find ${DATA_FOLDER} ${LOGS_FOLDER} -group 999 -exec chown -h 9999:9999 {} +

After these commands execute successfully, you can stop the migration container and delete it. The jahia container should now start as usual.