JATOS on DigitalOcean

On this page we want to explain how to install JATOS on a server running on DigitalOcean. We tried to keep this tutorial as easy as possible: if everything runs smoothly you don't have to use the terminal at all.

DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.) that is comparatively easy to use and has good documentation. They offer something called Droplets and One-Click Apps which is just a fancy name for a pre-installed server in the cloud. And btw. we have no connections to DigitalOcean whatsoever.

Keep in mind: A server in the cloud will cost money (depending on the size $5 to $50 / month) and you will need a credit card.

Setup a simple JATOS server on DigitalOcean

First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name.

1. Set up an account with DigitalOcean - you'll have to provide billing information.

2. Use this link to create a Droplet with Docker on Ubuntu pre-installed. Do not press Create yet - we need to set up things first.

   

   Your sreen should look similar to this one: Selected Marketplace with Docker x.x.x on Ubuntu x.x

3. Scroll down to Choose a plan: Droplet size depends on your experiments. Shared CPU that come with the Basic plan are usually enough (and cheaper). For the CPU options: Memory is often the scarce resource: Common numbers are 1GB, 2GB, 4GB for a single researcher or group - or 8GB for an institutional server. If you are not sure get the smaller one - you can always scale up later. If you just want to try it out: Regular Intel with 1GB for (currently) $5/month will do it.

4. Scroll down to Choose a datacenter region: You can actually use any you want, but best is to choose one that is near to your participants to reduce loading time.

5. Select additional options: Here activate User Data and copy+paste the following script in the text field:

   #!/bin/bash
   
   # Run JATOS as docker container
   docker run -d --restart=always -p 80:9000 jatos/jatos:latest

   

   The User Data should look similar to this screenshot here

6. You could also add an SSH key under Authentication / SSH keys. If you don't know what this is, set a Password. Keep the password somewhere safe. You will need it if you ever want to log into your server's terminal.

7. [Optional] Add backups

8. Finally click the Create button

9. Try out your JATOS: Now the server is being created which can take a couple seconds (or minutes). Copy the server's (aka Droplet) IP address into your browser's address bar and if everything went well, you will see a JATOS login screen.

10. Log into JATOS with ‘admin’ and password ‘admin’

11. The first thing you should do is change your admin password:

    1. Click on ‘Admin (admin) in top-right header
    2. Click ‘Change Password’

Voila, you have your own JATOS server.

DigitalOcean charges you by second. So if you want to create a new JATOS server because something went wrong, just Destroy the old one and start over.

Although usually not necessary, you can also access your server via SSH: ssh root@xx.xx.xx.xx (exchange xx.xx.xx.xx with your IP). Use the password you entered during creation of the Droplet. The first time you will be asked to change your password.

Deleting your server

Deleting the server is straightforward. In DigitalOcean, go to your Droplet -> in the left menu of your Droplet choose Destroy.

Now, you might want to use a nicer address than an IP and add some encryption-safety with HTTPS to your server - then read on.

Add HTTPS with Traefik and use your own domain name

This part is optional and is only necessary if you want to have your own domain name instead of an IP and use encryption (HTTPS).

We will use Traefik as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source and free to use.

Buy your own domain name: Sorry, we can't give you a domain name - you have to get your own. But there are plenty domain name registrars that help you with this business. Another option is to talk to your IT department and convince them to give you a subdomain for free.

Now with a domain name you can encrypt your server's communication with HTTPS.

To create a JATOS server with Traefik follow the instructions of the first paragraph (Setup a simple JATOS server on DigitalOcean) but in the User Data field of Select additional options put the following script:

#!/bin/bash

DOMAIN_NAME="my.domain.name"
EMAIL="my.email@foo.com"

curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/docker-compose.yaml > /root/docker-compose.yaml
curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/traefik.toml > /root/traefik.toml

sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/docker-compose.yaml
sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/traefik.toml
sed -i "s/<EMAIL>/${EMAIL}/g" /root/traefik.toml

touch /root/acme.json
chmod 600 /root/acme.json
docker network create proxy
docker-compose -f /root/docker-compose.yaml up -d

Exchange my.domain.name and my.email@foo.com with your own domain name and email address. Your email we need for encryption with Let's Encrypt.

This script downloads two config files, one for Traefik and one for Docker Compose. If you are interested you can examine them under https://github.com/JATOS/JATOS/blob/main/deploy/docker-compose.yaml and https://github.com/JATOS/JATOS/blob/main/deploy/traefik.toml. Docker Compose will start JATOS' and Traefik's container for us.

After you've created your Droplet you still have to point your domain name to your server's IP address. This involves dealing with things like A records or AAAA records or DNS servers and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

Then as a last step, after your domain name points to your server's IP, you have to reset your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and use HTTPS from now on. Sometimes it's necessary to restart a second time.

Done. You have a JATOS server with encryption on your domain name.