How to Compose an eXo Platform Docker


This guest post is extracted from an original article by Eric Taïeb Walch.Eric Taïeb Walch.

1. Introduction

This post explains how to build a dockerized eXo Platform following Docker’s core principle of “one task, one container.”

In this example, eXo platform will use MySql as the database to make it more production ready.

Also, eXo’s JCR data as well as MySql data will be stored in separate and dedicated Docker Data containers.
To link these containers, we will use the newly released docker-compose tool.

The final docker composition will look like this:


2. Container Descriptions

We will need 4 containers:

  • mysql
    • using the official mysql/mysql-server:latest image
  • mysqldata
    • will expose volume /var/lib/mysql
  • exoplf
    • using a tweaked exo platform image, supporting server.xml customization and custom jcr data volume
  • exodata
    • will expose volume /srv/exo where eXo’s JCR data will be stored

3. Container Docker Files

Let’s describe these containers.


We will pull the official mysql/mysql-server:latest available on DockerHub Registry here:

It supports the initial creation of the database and user through Environment variables.

You can change any of these, but note that you will need to adjust the server.xml file in the exo-plf container (described later).

This container will mount /var/lib/mysql from the mysql-data container.

Mysql Data

This container will store the Mysql data directory. It is very simple and its Dockerfile looks like this:

The important line here is:

It makes the /var/lib/mysql directory mountable by other containers.

DockerHub image is teknologist/mysql-docker-data, available at the DockerHub Registry here:

GitHub repo:

eXo Data

As above, this image will be used to spawn a container that holds /srv/exo directory.
This directory contains all the persistent data for eXo’s JCR files.

Again, it is very simple and its Dockerfile looks like this:

DockerHub image is teknologist/exo-data.

It is available at the DockerHub Registry:

The GitHub repo:

eXo Platform

This image is a fork of eXo’s original image.

Changes are:

  • Upgraded to PLF 4.2.0-RC1
  • Added MySQL JDBC Connector to lib/directory
  • Added server.xml to switch default HSQL database to MySQL
  • Added environment variables to setup mysql connection properties

The github repo for this Docker image is available here:

As you can see, the server.xml refers to a mysql database host named mysql.
This is important, as this is how containers are linked using docker-compose.

Short story:
If you name a container mysql and link it in the docker-compose.yml file, then docker-compose will set an entry in the host’s file named mysql pointing at the IP of the container.
This makes linking container trivial.

The Docker image is teknologist/ubuntu-jdk7-exo-mysql and is available at the DockerHub Registry here:

4. Docker composing these containers together

This is where the magic happens. By writing a simple 25 lines of docker-compose.ym, we will spawn an entire eXo platform infrastructure in minutes.

First of all, you need to have a recent docker version installed (1.3 or higher) for docker-compose to work.
As of this writing, I am using Docker version 1.6.2, build 7c8fca2.
You can find how to install a docker here:

The next step is installing docker-compose.
On supported platforms (GNU/Linux, OSX, etc.), this is as simple as entering the following commands:

See for more information.

Once your docker + docker-compose environment is ready, create a directory, exo-compose, for example. In that directory, create a file called docker-compose.yml with the following content:

Beware: This is a yaml file, so indentation is crucial. Gist available here.

As you can see, three things are important here and let you link everything together:

This directive instructs each container to mount the volumes from the respective data container.

This is the main compose directive that links exo platform to mysql. With this directive, docker-compose:

  • creates a network connection between the exo and mysql containers
  • creates an entry named mysql in eXo container’s /etc/hosts file pointing to the mysql container IP

If you look back at the server.xml file, this is how the mysql host in the jdbc connection string gets resolved.

You can find full docker-compose documentation here:

Last but not least, both mysql and exoplf services’ MYSQL_ environment variables:

NOTE: MYSQL_ROOT_PASSWORD is only needed in mysql service.

NOTE: I have updated the exoplf image to support MYSQL_ environment variables. It is now trivial to setup custom MySQL connection details. Just set the MYSQL_ environment variables correctly on both exoplf and mysql services in docker-compose.yml – Content has been updated in this post to reflect this.

Now you are ready to spawn the infrastructure. In the directory where you created the docker-compose.yml file, launch: docker-compose up

NOTE: If you want to run your services in the background, you can pass the -d flag (for daemon mode) to docker-compose up and then use docker-compose ps to see what is currently running. Of course, each docker container supports classic docker commands, so you could check exoplf’s logs via a docker logs commands.

I like to start the first time without -d so I can see what is going on in the initial containers set-up.

NOTE: Now the thing is that docker-compose starts containers fast and the initial startup of mysql creates the database and user, so at immediate startup exo’s container will show an error connecting to the database. You can ignore that because, while exo continues its start-up process, the database will become available. This happens only the first time, as the databases need to be created.

Depending on your docker’s host performance, after some time you’ll see:

You can connect to your docker’s host port 8080 (provided you didn’t change it in the docker-compose ports directive) and you’ll be greeted with the initial eXo setup page:


Complete the rest of the set-up wizard and you are set.

5. Operating your eXo/Mysql Docker composition

You can stop and start your infrastructure as you wish. Persistence data is kept in the data containers so there is no loss of data/configuration.

Stopping your existing infrastructure

If you started in foreground, hit [CTRL]-C.
If you started in background, enter: docker-compose stop

Note: You don’t see anything related to the data containers, as they don’t really run. They just provide volumes.

Starting your existing infrastructure

Again, enter: docker-compose start

To see what is currently running in your compose infrastructure

Enter: docker-compose ps

Again, you see the data containers are not in running state and that is normal.
Also note: mysql port 3306 is not exposed outside the container. Docker-compose does all the tunnelling for you.

To see your container’s logs

If you want to tail exoplf’s log, type: docker logs exocompose_exoplf_1

Again, each of these containers support all docker commands.

6. Final thoughts

As you can see, docker-compose makes building docker-based infrastructures very easy.

Other tools, such as Google’s Kubernetes, are very promising too. They not only let you compose but also scale (through minions—no, I didn’t invent that).

Another very promising tool I have used to explore docker composition on CoreOS is Rancher.

It looks like we are increasingly moving from VM-based cloud infrastructure to highly dense container-based ones. Think lower overhead (if not zero). Also think green!

Thanks for reading, sharing and +1-ing!

Thanks again to Eric Taïeb Walch for his great post. Make sure to check his original article as Eric will update his work regularly.

Join the eXo tribe by registering for the community and access tutorials, support, and downloads!

About Eric Taïeb Walch

Fifteen years in developing architectures for realtime web-based finance/e-trading, high availability, high performance using JavaEE and Open source software. Loves JBoss, Apache Group, GNU/Linux, Debian. Connect with Eric on LinkedIn.

Eric hosts the Teknologist’s Blog about “Systems, software design, architectures, experiences / experiments shared with the masses. 100% OpenSource. GNU is not Unix.”

Be part of the discussion, share your comments