Skip to main content
Version: 3.8.x

Update JATOS

We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. However if you are currently running a study it's always safest to keep the same JATOS version throughout the whole experiment.

Please do backups before updating.

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

There are more details about updating in their respective pages:

Automatic Update​

This is the recommended update method for JATOS running locally or on a simple server (but not in a cluster).

You can update your JATOS automatically if you have admin rights on JATOS and running on Mac OS or Linux. Windows is not yet supported.

The process is pretty self-explanatory, but anyway, we'll explain it here in detail:

  1. You will get a notification on your JATOS' Administration page.

    Update notification Schreenshot

    Sometimes your JATOS is not able to receive data about new releases. If this is the case and you know there is a new release that you would like to update to, you can still start the update by specifying the version.

  2. Click on Update, confirm that you want to continue and the latest JATOS version will be downloaded from GitHub and saved in your system's temporary folder. The download might take a while depending on your internet connection.

  3. After download is complete, you will be asked again for confirmation. Optionally you can do a backup: JATOS will copy the content of its own installation folder into a folder with the name backup_x.x.x (x.x.x is the version before the update). This will usually include your embedded H2 database, your study assets and logs - but not your MySQL database (should you have one). If anything goes wrong in the auto-update, you have everything in this backup folder to start the old JATOS again. This backup will use up disk space (that is why it is not selected by default).

    Update notification Schreenshot

  4. After clicking the Go on button, JATOS will stop itself, replace its program files and re-start itself again. This might take some time depending on the new version and your machine resources, but usually it's done within 2 minutes. Refresh your JATOS home page every now and then until you see your updated JATOS' login screen again.

  5. Check the new JATOS with the build-in tests: go to Administration ⇒ Tests and check that all tests are 'OK'.

(Auto-)Update to a specific version​

Sometimes, for whatever reasons, JATOS doesn't automatically detect new versions. Then you can still start the update by specifying the version.

It is usually destructive to update JATOS to a lower version than is currently installed. It's highly recommended to use a higher version (or the same). Use at your own risk.

The URL of JATOS administration page accepts the query parameter version. This parameter takes the JATOS version as specified in GitHub and enforces an update to this version.

E.g. if the version you want to update to is v3.7.4 (don't forget the 'v') and your domain is my.jatos.org, than the URL for your browser is:

https://my.jatos.org/jatos/admin?version=v3.7.4

The rest of the update procedure is the same as in the normal automatic update: you will be asked for confirmation twice.

JATOS uses Java 11 - older versions use Java 8. Future versions will likely require newer Java versions. If you're updating from a JATOS version using Java 8 to (say) another version using Java 11, the auto-update process will automatically download JATOS bundled with the new Java, regardless of which variant you are currently using. If you do not like the bundled Java and use your own version you can always remove the folder jre later on after the update.

Manual Update​

The automatic update is the preferred way but if, for whatever reason, you do not trust JATOS' automatic update or it does not work for you (e.g. you run a server on Windows), you can still update JATOS manually.

You can update your JATOS manually in two main ways: 1) Easy, but discarding all results, and 2) Not so easy, but keep everything.

Easy, but discard results​

If you don't care about result data stored in JATOS:

  1. Export any studies you wish to keep from the old JATOS installation.
  2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
  3. Stop the old JATOS and start the new JATOS.
  4. Import all the studies your previously exported. This will transfer the files and subfolders in your study's asset folder (HTML, JavaScript, CSS files).

What will be transferred:

  1. Files and subfolders in study's assets folder
  2. All your studies' and components' properties
  3. The properties of the first (Default) batch

What will be lost:

  1. All result data and files will be lost
  2. All workers in all batches (including Default batch)
  3. All batches other than the Default batch
  4. Any configuration you did in jatos.conf
  5. All study logs

Not so easy, but keep everything​

JATOS stores its state in several folders in the file system and a database and you will have to transfer everything to the new, updated JATOS.

  • The study assets root folder stores all your study's files (e.g. HTML, JS, CSS, images). By default it's in your JATOS folder and has the name study_assets_root.
  • The result uploads folder stores all your study result files. By default it is in your JATOS folder and has the name result_uploads.
  • The study logs folder stores all your study logs. By default it is in your JATOS folder and has the name study_logs.
  • JATOS' application logs are stored by default in your JATOS folder under a folder with the name logs.
  • If you use the embedded database then all its data is, by default, stored in a folder called database within your JATOS folder.
  • If you use a MySQL/MariaDB database your data are stored there and you only have to configure the updated JATOS to use this database.
  • You might have configured JATOS by changing it's jatos.conf file. By default it is in the JATOS installation folder in the folder conf.

Then the update procedure is:

  1. Stop JATOS.
  2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
  3. From the folder of your old JATOS installation copy the study assets root folder, result uploads folder, study logs folder, application logs folder, the database folder (if you do not use MySQL/MariaDB), and the jatos.conf into the folder of your new, updated JATOS.
  4. Start the new JATOS.

What will be transferred:

  1. All study assets
  2. All your study and component properties
  3. All batches, together with their workers, and generated study links
  4. All result data and files
  5. All study logs
  6. All logs
  7. JATOS' configuration (as long as it is done in the configuration file)

What will be lost: nothing