To run studies online, JATOS has to be installed on a server. Server instances of JATOS have slightly different configuration requirements than local instances. This text aims at server admins who wants to setup a server running JATOS and who know their way around server management.
Edit me

There are several ways to bring JATOS to the internet. You can install it

If you don’t know much about server administration the DigitalOcean page might be best for you.

Installation on a server

The actual JATOS instance on a server isn’t too different from a local one. It basically involves telling JATOS which IP address and port it should use and (optionally) replace the H2 database with a MySQL one. There are other issues however, not directly related to JATOS, that you should consider when setting up a server. These include: setting up automatic, regular backups of your data, an automatic restart of JATOS after a server reboot, encryption, additional HTTP server, etc.

1. Install Java

We’ve produced multiple versions of JATOS. The simplest version is JATOS alone, but other versions are bundled with Java JRE. On a server, it’s best (though not necessary) to install JATOS without a bundled Java. This will make it easier to upgrade to new Java releases.

2. [Optional] Install MySQL

By default JATOS uses an embedded H2 database and no further setup is necessary but it can be easily configured to work with a MySQL database.

Possible scenarios why one would use an external database are

  • the expected traffic is rather high and many users will run studies with many participants and the studies will store a lot of data in the database
  • to be able to do a regular database backup
  • higher trust in the reliability of MySQL (although we never had problems with H2)

One could install the external database on the same server as JATOS is running or on an extra server depending on ones need.

To let JATOS access MySQL it needs a database user called ‘jatosuser’ and a database called ‘jatos’. One way to set up MySQL is this one:

  1. Install MySQL (e.g. sudo apt install mysql-server on Ubuntu)

    JATOS requires MySQL >= 5.5

  2. Log in: mysql -u root -p

  3. Create a user for JATOS (change ‘password’) GRANT ALL PRIVILEGES ON *.* TO 'jatosuser'@'localhost' IDENTIFIED BY 'password';

  4. Log out and log in with the newly created user: mysql -u jatosuser -p

  5. Create a database for JATOS: CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Appart from giving JATOS access to the database it is not necessary to set it up any further, e.g. to create any tables - JATOS is doing this automatically.

Don’t forget to configure JATOS to use your MySQL.

3. Install JATOS

  1. Download JATOS

    E.g. with wget for the version 3.2.1:

    wget https://github.com/JATOS/JATOS/releases/download/v3.2.1/jatos-3.2.1.zip

  2. JATOS comes zipped. Unpack this file at a location in your server’s file system where JATOS should be installed.

  3. Check that the file loader.sh in the JATOS folder is executable.

  4. Check that JATOS starts with loader.sh start|restart|stop

4. Configuration

If JATOS runs locally it’s usually not necessary to change the defaults but on a server you probably want to set up the IP and port or maybe use a different database and change the path of the study assets root folder. These docs have an extra page on how to Configure JATOS on a Server.

5. Change Admin’s password

Every JATOS installation comes with an Admin user that has the default password ‘admin’. You must change it before the server goes live. This can be done in JATOS’ GUI:

  1. Start JATOS and in a browser go to JATOS login page http://your-domain-or-IP/jatos
  2. Login as ‘admin’ with password ‘admin’
  3. Click on ‘Admin (admin) in top-right header
  4. Click ‘Change Password’

6. Check JATOS’ test page

JATOS comes with a handy test page http://your-domain-or-IP/jatos/test. It shows some of the current configuration and system properties. Above all it does some tests, e.g. WebSockets connections and database connection. Check that all tests show an ‘OK’.

7. [Optional] Proxy and encryption

Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it’s necessary to support them).

8. [Optional] Auto-start JATOS

It’s nice to have JATOS starts automatically after a start or a reboot of your machine. Choose between one of the two possibilities: 1) via a systemd service (JATOS version >= 3.1.6, recommended), or 2) via a init.d script.

1) Via systemd service (JATOS version >= 3.1.6, recommended)

Create a systemd service file for JATOS

vim /etc/systemd/system/jatos.service

and put the following text inside.

[Unit]
Description=JATOS
After=network-online.target
# If you use JATOS with an MySQL database use
#After=network-online.target mysql.service

[Service]
PIDFile=/my/path/to/jatos/RUNNING_PID
User=my-jatos-user
ExecStart=/my/path/to/jatos/loader.sh start
ExecStop=/bin/kill $MAINPID
ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
ExecRestart=/bin/kill $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Change the paths and the user according to your JATOS path and the user you want to start JATOS with.

Secondly, notify systemd of the new service file:

systemctl daemon-reload

and enable it, so it runs on boot:

systemctl enable jatos.service

That’s it.

Additionally you can manually start/stop JATOS now with:

  • systemctl start jatos.service
  • systemctl stop jatos.service
  • systemctl restart jatos.service
  • systemctl status jatos.service

You can disable the service with systemctl disable jatos.service. If you change the service file you need systemctl daemon-reload jatos.service to let the system know.

2) Via /etc/init.d script

It’s easy to turn the loader.sh script into an init script for a daemon.

  1. Copy the loader.sh script to /etc/init.d/
  2. Rename it to jatos
  3. Change access permission with chmod og+x jatos
  4. Edit /etc/init.d/jatos
    1. Comment out the line that defines the JATOS location dir="$( cd "$( dirname "$0" )" && pwd )"

    2. Add a new locatoin dir= with the path to your JATOS installation

      The beginning of your /etc/init.d/jatos should look like:

      #!/bin/bash
# JATOS loader for Linux and MacOS X
      
# Change IP address and port here
# Alternatively you can use command-line arguments -Dhttp.address and -Dhttp.port
address="127.0.0.1"
port="9000"
      
# Don't change after here unless you know what you're doing
###########################################################

# Get JATOS directory
#dir="$( cd "$( dirname "$0" )" && pwd )"
dir="/path/to/my/JATOS/installation"
...

       

  5. Make it auto-start with the command sudo update-rc.d jatos defaults

Now JATOS starts automatically when you start your server and stops when you shut it down. You can also use the init script yourself like any other init script with sudo /etc/init.d/jatos start|stop|restart.

9. [Optional] Backup

The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularily.

But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of two parts (1.) the data stored in the database and (2.) your study assets folder that contains all the web files (e.g. HTML, JavaScript, images). Both have to be backed up to be able to restore them later on.

  1. Database
    • MySQL - If you use a MySQL database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > mysql_bkp.out you can backup the whole data into a single file. Restore the database with mysql -u myusername -p mydbname < mysql_bkp.out.
    • H2 - There are at least two ways: one easy (but unofficial) and one official:
      1. Copy & paste the db file - It’s important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might be corrupted. You can just backup the folder my-jatos-path/database. In case you want to restore an older version from the backup just replace the current version of the folder with the backed-up version.
      2. Via H2’s upgrade, backup, and restore tool
  2. Study assets root folder - You can just make a backup of your study assets folder. If you want to return to a prior version replace the current folder with the backed-up version.

Remember, a backup has to be done of both the database and the study assets root folder.