Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.
JATOS needs Java 8 or 11 to run (17 is not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.
E.g. the latest release:
E.g. or a certain version (exchange x.x.x with the version you want):
JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:
Check that the file
loader.shin the JATOS folder is executable. If not:
chmod u+x loader.sh
And to stop it:
Ctr+Cdoes the job, but if your JATOS runs in the background:
Check JATOS is running correctly:
curl http://localhost:9000/pingshould give you
If you can already access your server from the outside, open JATOS in a browser (the default port is 9000):
http://my-IP-or-domain:9000. It should show the JATOS login screen. You can 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 an 'OK'. Click on System Info and check that all is like you configured it.
Always change admin's password
This can be done in JATOS' GUI:
- In a browser go to JATOS' login page
- Log in as 'admin' with password 'admin'
- Click on Admin (admin) in top-right header
- Click Change Password
- In a browser go to JATOS' login page
[Optional] Install MySQL/MariaDB
See JATOS with MySQL
These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.
[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).
[Optional] Auto-start JATOS via systemd
It's nice to have JATOS start automatically after a start or a reboot of your machine.
Create a systemd service file for JATOS. E.g. with vim:
and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):
# If you use JATOS with an MySQL database use
ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
Secondly, notify systemd of the new service file:
and enable it, so it runs on boot:
systemctl enable jatos.service
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 to do
systemctl daemon-reload jatos.service again to let the system know.
[Optional] Specify the location of JATOS' data folders
By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.
JATOS' data folders (and their path configuration):
One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:
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 this would be:
-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"
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 regularly.
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 several parts and all have to be backed up to be able to fully restore JATOS later.
If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.
JATOS data folders
JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.
If you use a MySQL or MariaDB database you might want to look into the
mysqldumpshell command. E.g., with
mysqldump -u myusername -p mydbname > mysql_bkp.outyou can backup the whole data into a single file. Restore the database with
mysql -u myusername -p mydbname < mysql_bkp.out.
Backup H2 database
There are at least two ways to backup an embedded H2 database: one easy (but unofficial) and one official:
Easy way: Just backup the database folder in your JATOS installation folder. But it is important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might get corrupted.
Official way: Use H2's upgrade, backup, and restore tool
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 on a server: