Install JATOS via Docker

JATOS' Docker images are hosted at hub.docker.com/r/jatos/jatos/.

Docker is a great technology, but if you never heard of it you can safely ignore this page (it's not necessary to use it if you want to install JATOS, either locally or on a server).

Also have a look at JATOS with Docker Compose for some advanced Docker setup.

Installation with Docker

1. In your terminal:

   • Get the latest release:

   docker pull jatos/jatos:latest
   • or a specific release (exchange x.x.x with the version):

   docker pull jatos/jatos:x.x.x

2. Run JATOS (change latest to your version)

   docker run -d -p 80:9000 jatos/jatos:latest

   The -d argument specifies to run this container in detached mode (in the background) and the -p is responsible for the port mapping.

3. You can check that the new container is running correctly:

   In the following instructions, if you are on a remote host, change 127.0.0.1 to your IP/domain.

   • Use docker ps in the terminal: in the line with jatos/jatos the status should say up
   • Use curl: curl http://127.0.0.1/ping should give you pong back
   • In a browser go to http://127.0.0.1 - it should show the JATOS login screen
   • Check JATOS' administration page: http://127.0.0.1/jatos/admin
     • Run the Tests: all should show an 'OK'
     • Check the System Info that it is all like you configured it

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

Debugging and Troubleshooting

To get the logs add the argument -Djatos.logs.appender=ASYNCSTDOUT and run the container not detached:

docker run -p 9000:9000 jatos/jatos:latest -Djatos.logs.appender=ASYNCSTDOUT

Change port

With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' Docker container). Just use docker's -p argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use:

docker run -d -p 80:9000 jatos/jatos:latest

Configuration with Docker

JATOS running in a Docker container can be configured the same way as running it the normal way: via a configuration file, via environment variables, or command line arguments. Have a look at JATOS Configuration for the possibilities.

Via arguments

Add as many arguments to the end of the docker command as you wish.

E.g. to run JATOS with a MySQL database running on localhost (not in a container), with the default port 3306, use the following command (change username and password to your MySQL user):

docker run -d --network="host" jatos/jatos:latest \
    -Djatos.db.url='jdbc:mysql://localhost/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' \
    -Djatos.db.username='jatosuser' \
    -Djatos.db.password='my-password' \
    -Djatos.db.driver='com.mysql.cj.jdbc.Driver'    

Via environment variables

All environment variables that can be used to configure a normal JATOS server installation can be used in a Docker installation. Just use docker's -e argument to set them.

E.g. to run JATOS with a MySQL database running on localhost (not in a container), with the default port 3306, use the following command (change username and password to your MySQL user):

docker run -d --network="host" \
    -e JATOS_DB_URL='jdbc:mysql://localhost/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' \
    -e JATOS_DB_USERNAME='jatosuser' \
    -e JATOS_DB_PASSWORD='my-password' \
    -e JATOS_DB_DRIVER='com.mysql.cj.jdbc.Driver' \
    jatos/jatos:latest

Via configuration file

You can mount a configuration file (jatos.conf) as a Docker volume in the container. This way you can comfortably edit the jatos.conf in your local file system.

E.g. with a jatos.conf in the current working directory:

docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

Persist data with volumes

Volumes are the preferred way to persist data with Docker containers. This can be necessary if one wants to update JATOS or do backups.

Before using a volume one has to create it:

docker volume create --name jatos_data

In JATOS' Docker container all data are stored, by default, in the folder /opt/jatos_data (although this can be configured). Now you can mount the newly created volume jatos_data at this location:

docker run -d -p 9000:9000 --volume jatos_data:/opt/jatos_data jatos/jatos:latest

Updating JATOS with Docker

Be aware: JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. Please do backups before updating.

There are two possibilities to update JATOS running in a Docker container:

1. Unless you run JATOS on multiple nodes, you can simply use the auto-update feature to update JATOS to newer versions.

2. Another way, arguably even simpler, is to just change the Docker image tag of JATOS to a newer version. Stop the current running JATOS container and run a new one with the new version tag. But this only works if you persist your data with volumes - If you don't use volumes your data stored in JATOS will be lost.