Liferay and Docker: Upgrade Liferay to 7.0 GA6

Liferay Portal 7.0 CE GA6 Release was announced about 2 weeks ago and Liferay containerisers may desire to upgrade their Docker container to the new Liferay version. Well, this is a not so hard task to accomplish, but some steps can be not so obvious the first time one faces them. This is the reason behind this little guide on how to migrate from GA5 to GA6 inside a Docker container.

Local environment update

The first step is to migrate the local development environment to the next Liferay version. This phase is equal for both normal and containerised workspaces. In order to update the local environment,it's necessary to:

  • Update the liferay.workspace.bundle.url property inside gradle.properties file to
    liferay.workspace.bundle.url=https://cdn.lfrs.sl/releases.liferay.com/portal/7.0.5-ga6/liferay-ce-portal-tomcat-7.0-ga6-20180320170724974.zip
  • Run the bundle/initBundle gradle task

Docker container update

Now that the development workspace has been migrated, it's necessary to update the Liferay Docker container. The liferay.home path on the new container may differ from the path inside the GA5 container. For the sake of convenience, GA6_LIFERAY_HOME variable will be used to refer to the liferay.home path on the new container, while GA5_LIFERAY_HOME refers to the liferay.home path inside the old container. For Liferay containers inside my Github repo, the two liferay.home paths are the following

GA5_LIFERAY_HOME=/usr/local/liferay-ce-portal-7.0-ga5
GA6_LIFERAY_HOME=/usr/local/liferay-ce-portal-7.0-ga6

In order to update the Docker container, it's necessary to:

  • Change the Docker image inside docker-compose.yml file
    image: glassofwhiskey/liferay-portal:7.0-ce-ga6-dev
    
  • Update all portal container volumes inside docker-compose.yml so that they stop pointing to GA5_LIFERAY_HOME, but point to GA6_LIFERAY_HOME instead
    volumes:
       - liferay-document-library:GA6_LIFERAY_HOME/data/document_library
       - ${LIFERAY_BUNDLE_DIR}/osgi/configs:GA6_LIFERAY_HOME/osgi/configs
       - ${LIFERAY_BUNDLE_DIR}/portal-ext-properties:GA6_LIFERAY_HOME/portal-ext.properties
       ...
    
  • Update the liferay.home property inside portal-ext.properties file to point to GA6_LIFERAY_HOME and copy the updated file inside the bundles folder.
    liferay.home=GA6_LIFERAY_HOME
    

Database upgrade

The brand new Liferay container it's almost ready now, but a last step is still missing. Indeed, launching startDockerEnv will result in an exception thrown during the server startup phase: you need to upgrade your DB first!!!

This is the not so obvious task of a containerised upgrade. Normally, it would be enough to open a shell inside your bundles/tools/portal-tools-db-upgrade-client folder and type the following command

java -jar com.liferay.portal.tools.db.upgrade.client.jar

But this will not work so well in a Dockerised architecture, with Liferay and DB running inside containers. In such case, it's necessary to run the aforementioned command from inside the Liferay container. Nevertheless, in order to be able to do that, the docker-compose.yml file must be modified a bit:

  • As a first thing, it's necessary to see the bundles/tools folder inside the container. The first step is therefore to add a new bind mount to the portal container
    volumes:
       ...
       ${LIFERAY_BUNDLE_DIR}/tools:GA6_LIFERAY_HOME/tools
  • Then it's necessary to be able to execute the upgrade client inside the container. Therefore, Liferay must not start automatically when the startDockerEnv task is invoked. What is needed instead is a Liferay container that hangs forever doing nothing, so that the upgrade client can execute its tasks undisturbed. In order to achieve this goal, the following line should be added to the docker-compose.yml file
    entrypoint: "tail -f /dev/null"

Now it's time to execute the startDockerEnv task, wait for the containers to start and run the following command to execute the DB upgrade client from inside the Liferay container, where LIFERAY_CONTAINER_NAME is the name of the Liferay Docker container.

docker exec -it LIFERAY_CONTAINER_NAME java -jar GA6_LIFERAY_HOME/tools/portal-tools-db-upgrade-client/com.liferay.portal.tools.db.upgrade.client.jar

This command will start an interactive shell with the DB upgrade client. From now on, all informations reported here are perfectly valid and the upgrade process can be completed as usual.

Under some conditions, the DB upgrade client may thow a file permissions related exception at the end of the configuration phase. In such case, it's necessary to run the previous command as the root user. In order to accomplish that, this modified version of the command must be used:

docker exec -it --user="root" LIFERAY_CONTAINER_NAME java -jar GA6_LIFERAY_HOME/tools/portal-tools-db-upgrade-client/com.liferay.portal.tools.db.upgrade.client.jar

Conclusions

And here it is. After the upgrade process completion, Liferay DB will be ready to support the GA6 portal. All that remains to do is to run the stopDockerEnv task, remove the additional lines from the docker-compose.yml file and restart the whole thing. Et voila! A fully upgraded GA6 containerised development environment is ready to be explored.

If you face some issues during the upgrade process, please don't be afraid to report them hereunder: I (or someone from the Liferay containerisers community) will try to help you.

Happy Liferay upgrading!!!