Skip to main content
Version: next

JATOS with Docker Compose

Docker Compose offers an easy way to set up a JATOS installation with a MySQL database and Nginx as an reverse proxy for, among other things, HTTPS encryption.

Get started​

Example repository​

We assembled all necessary files in a git repository that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

git clone https://github.com/JATOS/JATOS_with_docker_compose.git

The important files in the repo are compose.yaml to set up docker compose, nginx.conf for Nginx, and jatos.conf for JATOS.

JATOS_with_docker_compose
├── compose.yaml
├── nginx.conf
├── jatos.conf
└── ...

The docker compose file compose.yaml starts three services:

  1. Nginx as a reverse proxy that does encryption (HTTPS)
  2. JATOS
  3. A MySQL database

Additionally it creates three shared volumes:

  1. jatos-data - stores JATOS' data folders: study assets, result uploads, study logs and JATOS' tmp folder
  2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
  3. jatos-db - where MySQL stores its data

Up​

Go into the cloned folder and start the services with:

docker compose -f compose.yaml up

If everything went smoothly, you will now see the JATOS login page under: https://localhost/

With Ctrl+C you can stop the services. Removing the stopped containers can be achieved with docker compose -f compose.yaml down and additionally removing all the volumes by adding the -v flag: docker compose -f compose.yaml down -v.

Check that it runs​

First visit the JATOS admin page: https://localhost/jatos/admin. There, check that all Tests are OK. Also check that the System Info contains the configuration you intended.

Next, you can import a study (e.g. one from the Example Studies) and check if it runs well. Check, for example, that the result data appear in the results page.

Last but not least: Check that all data are persisted: First, stop and remove the containers (but not the volumes!) with docker compose -f compose.yaml down. Then, restart the services with docker compose -f compose.yaml up. Now check that all studies and their result data are still there.

Nginx configuration​

Have a look at JATOS with Nginx and configure Nginx to your needs. The file nginx.conf in our repo is mounted in Nginx' container and will be used by Nginx.

Use your own certificate (for HTTPS)​

The certificate used here in this example setup is self-signed and utterly insecure. The certificate files are mounted as volumes in the proxy service. You might have to change the file names (and paths) in nginx.conf too. 

volumes:
    - ./nginx-selfsigned.crt:/etc/ssl/certs/nginx-selfsigned.crt:ro
    - ./nginx-selfsigned.key:/etc/ssl/private/nginx-selfsigned.key:ro

MySQL configuration​

The following changes should be done in the compose.yaml:

Search and set JATOS_DB_PASSWORD and MYSQL_PASSWORD to the same password of your choice.

Search and set MYSQL_ROOT_PASSWORD, MySQL's root password to one chosen by you.

Consider to turn off MySQL's binary log with --skip-log-bin in db's command section.

Check JATOS with MySQL for more information.

JATOS configuration​

Have a look at JATOS Configuration.

Change the image version in the compose.yaml to the one you need (e.g. the latest one).

Always change the admin's password after first installation: Go to https://localhost/jatos/user/admin and and press button Change Password.

Debugging and logging​

You can redirect JATOS logs to stdout with -Djatos.logs.appender=ASYNCSTDOUT in the command section of the jatos service - or write the logs to a file with -Djatos.logs.appender=ASYNCFILE (which is actually the default and you can just leave it out). Logging to stdout is useful for debugging and is also used in advanced logging solutions. If you log to stdout you don't need an extra log volume and you can remove jatos-logs.

Using jatos.conf​

JATOS can be configured either by command parameters (the ones with the -D prefix) in the compose.yaml or with the jatos.conf configuration file. You can also set up some environment variables (like the JATOS_DB_PASSWORD). In the end it's up to you which way you prefer.

The jatos.conf file is mounted as a volume in the JATOS container. This way you can comfortably edit your jatos.conf outside of the container.

More about JATOS' Configuration with all possible parameters.

Updating JATOS with Docker Compose​

The easiest way to update a JATOS instance running with this setup with external data volumes is to just change the JATOS' Docker image tag to a higher version and restart the services. No need to use JATOS' auto-updater. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. And please do backups before updating.

Running JATOS on multiple nodes​

Have a look at JATOS in a cluster.