Install JATOS on a server

There are several ways to bring JATOS online. If you don't have much experience with server administration, the DigitalOcean page might be best for you.

There are also dedicated pages for installation with Docker and Docker Compose.

Installing JATOS as an Internet server usually involves replacing the embedded database with MySQL/MariaDB and setting up a reverse proxy (mainly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

Install Java

JATOS requires Java 11 to run (higher versions are not yet supported). You can install your own Java or download a JATOS version that is already bundled with Java.

Install JATOS

1. Download JATOS

   Example for the latest release:

   wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

   Or for a specific version (replace x.x.x with the version you want):

   wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

2. Unpack the zip file at your desired installation location:

   unzip jatos.zip

3. Ensure the loader.sh file in the JATOS folder is executable. If not:

   chmod u+x loader.sh

4. Start JATOS:

   ./loader.sh start

   To stop it:

   • Usually Ctrl+C does the job, but if JATOS runs in the background:

     ./loader.sh stop

5. Check that JATOS is running correctly:

   • Use curl: curl http://localhost:9000/ping should return pong.
   • If your server is accessible from the outside, open JATOS in a browser (default port is 9000): http://my-IP-or-domain:9000. You should see the JATOS login screen. Log in with username admin and password admin.
   • Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show 'OK'. Click on System Info and verify your configuration.

6. Always change the admin password:

   • In your browser, go to JATOS' login page: http://my-IP-or-domain/jatos
   • Log in as 'admin' with password 'admin'
   • Click on Admin (admin) in the top-right header
   • Click My Password to change it

[Optional] Install MySQL/MariaDB

See JATOS with MySQL.

Configuration

See the JATOS Configuration page for more options, such as enabling user authentication with ORCID, OpenID Connect (OIDC), LDAP, or Google Sign-in.

[Optional] Proxy and Encryption

Most admins use a reverse proxy in front of JATOS, mainly for encryption. We provide example configurations for both Nginx and Apache. Both support encryption and WebSockets (JATOS relies on WebSockets, so support is necessary).

• JATOS with Nginx
• JATOS with Apache

[Optional] Auto-start JATOS via systemd

To have JATOS start automatically after a reboot, create a systemd service file. For example, with vim:

vim /etc/systemd/system/jatos.service

Add the following (adjust the JATOS path and user as needed):

[Unit]
Description=JATOS
After=network-online.target
# If you use JATOS with MySQL, 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
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Reload systemd and enable the service:

systemctl daemon-reload
systemctl enable jatos.service

You can now manually control JATOS with:

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

Disable the service with systemctl disable jatos.service. If you change the service file, run systemctl daemon-reload again.

[Optional] Specify the Location of JATOS' Data Folders

By default, all data folders are in the JATOS installation folder. You may want to change their location for easier backups or updates.

JATOS' data folders (and their path configuration):

• study assets root folder
• result uploads folder
• study logs folder

To move all data folders to a single 'data' directory, set these properties in your config file:

jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

Or with command-line arguments:

-Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

[Optional] Backup

The easiest way to back up is to have JATOS users export their own data using the export function for result data. Encourage everyone to export their data regularly.

If you want to set up regular backups for all JATOS data, you need to back up several parts to fully restore JATOS later.

Simple

If you haven't changed any data folder paths, you can simply back up the whole JATOS folder. If you use the embedded H2 database, stop JATOS before backing up. If you use MySQL, back up the MySQL database separately.

Detailed

1. JATOS data folders:
   It's easiest to have all data folders in one directory. Then you can back up this directory with your preferred file backup tool.

2. Backup MySQL/MariaDB:
   Use the mysqldump command. For example:

   mysqldump -u myusername -p mydbname > jatos_bkp.sql

   Restore with:

   mysql -u myusername -p mydbname < jatos_bkp.sql

3. Backup H2 database:
   There are two ways:

   • Easy (but unofficial): Back up the database folder in your JATOS installation. Stop JATOS before backing up or restoring the H2 database this way, or your data may be corrupted.
   • Official: Use H2's upgrade, backup, and restore tool.

Update JATOS

Note: JATOS only allows updates to higher version numbers—downgrading will likely break your installation. Always back up before updating.

There are two ways to update JATOS running on a server:

1. Use the auto-update feature.
2. If you specified a separate 'data' folder, you can install a new JATOS (without starting it yet), stop the current JATOS, configure the new one to use your data folder, and then start it.