Skip to main content
Version: next

JATOS on DigitalOcean

Here we explain how to install JATOS in the cloud by using DigitalOcean. DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.). We provide this example because DigitalOcean is comparatively easy to use and has good documentation - but we have no connection to DigitalOcean whatsoever.

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

Set up a simple JATOS server on DigitalOcean​

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

DigitalOcean offers something called Droplet, that is basically a virtual machine, and we want to use it as a server for JATOS. If everything runs smoothly you don't have to use the terminal at all. You can watch the video here or follow the instructions further down.

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

  2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

  3. Choose the Region that is nearest to your users.

  4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

  5. Choose a Size: For Droplet type often Basic is enough and for CPU options: Regular. Choose memory 1 to 4 GB according to your expected server load. Don't spend to much time on this, choose the smaller one - you can increase the size later on. If you just want to try it out: a Regular with 1GB for will do it.

  6. Choose an authentication method

  7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

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

    You can change 'latest' to the specific version you need.

  8. Finally click the Create Droplet button

  9. Try out your JATOS: Now the server is being created which can take a couple 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 in with the default credentials 'admin' and 'admin'.

Done! Now you have a basic JATOS server accessible from the Internet.

Don't forget to change your admin user's password. Go to the admin user page (top-right corner) and and press button Change Password.

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

Destroy your JATOS server​

If you want to destroy your server, go to your Droplet's page in DigitalOcean and click on More -> Destroy. This will completely remove your JATOS server and delete all data that was collected with it. It will also delete any studies you uploaded.

Set up JATOS with HTTPS and a domain​

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.

Get 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 (just search for "domain registrars"). 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.

But first a summary of the work flow:

  1. Create droplet
  2. Set up your DNS
  3. Restart droplet
  4. Wait until you can reach the webpage

Create Droplet​

To create a JATOS server with Traefik follow the instructions of the first section (Set up a simple JATOS server on DigitalOcean) but in the field for the Add Initialization scripts put the following script:

#!/bin/bash

# Change to your email and domain (for Let's Encrypt)
email=myemail@example.org
domain=my.domain.org

cat >/root/compose.yaml <<EOL
version: "3.8"

services:

  traefik:
    image: "traefik:v2.10"
    container_name: "traefik"
    command:
      #- "--log.level=DEBUG"
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
      #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
      - "--certificatesresolvers.jatosresolver.acme.email=${email}"
      - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

  jatos:
    image: "jatos/jatos:latest"
    container_name: "jatos"
    ports:
      - "9000:9000"
    volumes:
      - "jatos-logs:/opt/jatos/logs"
      - "jatos-data:/opt/jatos_data"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
      - "traefik.http.services.jatos.loadbalancer.server.port=9000"
      - "traefik.http.routers.jatos.entrypoints=websecure"
      - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

volumes:
  jatos-data:
  jatos-logs:
EOL

docker compose -f /root/compose.yaml up -d

This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

Set up your DNS​

After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar 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).

Restart​

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

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

Misc​

  • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

    - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

    This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

  • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

  • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

    E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        command:
          - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
        ...

    E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        command:
          - '-Djatos.db.url=jdbc:mysql://1.2.3.4:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC'
          - '-Djatos.db.username=jatosuser'
          - '-Djatos.db.password=mypassword'
          - '-Djatos.db.driver=com.mysql.cj.jdbc.Driver'
        ...