Skip to main content

Installation

This page explains how to install Judgels, step-by-step. These steps will install Judgels using our Ansible scripts, which will deploy the Docker images of the apps.

A. Preparing local workstation​

We will install Judgels by running an Ansible playbook from a local workstation, which could be your own laptop or another VM. Make sure that the local workstation has Ansible installed.

B. Setting up deployment env directory​

  1. On the local workstation, clone the Judgels repository (https://github.com/ia-toki/judgels).
    • We'll assume that we clone to ~/judgels.
  2. Go to deployment. In this directory, you will see multiple deployment playbook directories, in the form of <major Judgels version>-<Ubuntu version>.
  3. Pick one of the directories. It is highly recommended that the VMs you spin up later have the exact same OS. For the purpose of this documentation, let's say you pick v3-ubuntu-24.04.
    • The major version in the directory name must match the Judgels version you are deploying. v2-ubuntu-24.04 only works for Judgels 2.x, and is kept for existing deployments that have not migrated yet. To deploy Judgels 3.x, pick a v3- directory.
    • If you are upgrading an existing Judgels 2.x deployment, follow the Migrating from v2 to v3 guide instead of this page.
  4. Copy the directory deployment/v3-ubuntu-24.04/ansible/env-example from the cloned Judgels repository. We'll assume that we copy it and rename as ~/judgels-env:
    cp -R ~/judgels/deployment/v3-ubuntu-24.04/ansible/env-example ~/judgels-env
  5. Inside deployment/v3-ubuntu-24.04/ansible, create a symbolic link to the env directory as env:
    cd ~/judgels/deployment/v3-ubuntu-24.04/ansible
    ln -s ~/judgels-env env

This directory consists of two files: hosts.ini and vars.yml. They describe the parameters of a Judgels deployment.

  • hosts.ini is an Ansible inventory describing the VMs to which Judgels is to be deployed.
  • vars.yml is a file containing environment variables, which will be used in for Ansible playbook roles during deployment.

It is recommended to track this env directory in a version control as the source of truth of our Judgels deployment. We will fill the values in both files in the next steps.

C. Spinning up VMs​

As mentioned in the Concepts page, we need to spin up 1 core VM and 1 or more grader VMs. The VMs have the following requirements:

  • Linux. In particular, we have tested that Judgels works on Ubuntu 22.04 LTS and 24.04 LTS.
  • Can be accessed from the local workstation to a root user via SSH.

Now, open hosts.ini:

  1. Fill the public IP of the core VM under the [core] section.
  2. Fill the public IP(s) of grader VM(s) under the [grader] section. Note that we can add multiple lines, one for each IP.

D. Generating passwords​

In vars.yml, generate different random strings for these values:

  • db_root_password
    • The root password of the MySQL installation.
  • db_password
    • The password of the judgels database.
  • superadmin_initialPassword:
    • The password for the auto-generated initial superadmin user.
  • rabbitmq_password
    • The password for the server and grader apps to connect to RabbitMQ.

E. Setting up domains​

  1. Purchase a domain (for example: mycontest.org). Then, set up the following (sub)domains.
    • mycontest.org
    • api.mycontest.org
    • admin.mycontest.org
  2. For each of the subdomains above, set up an A record pointing to the core VM's public IP.
  3. Open vars.yml, and modify the following config:
    • nginx_domain_judgels_client: mycontest.org
    • nginx_domain_judgels_server_api: api.mycontest.org
    • nginx_domain_judgels_server_admin: admin.mycontest.org
    • nginx_certbot_email: your email, used for obtaining SSL certificates from Let's Encrypt.

F. Running Ansible playbooks​

  1. Go to deployment/v3-ubuntu-24.04/ansible.
  2. Optional: if the Ubuntu version that you picked is the latest version, you can edit the Judgels version value in env/vars.yml, e.g.:
    app_version: '3.0.0'
    You can get the latest version from https://github.com/ia-toki/judgels/releases. Enter the version without the v prefix. DO NOT edit the version if the Ubuntu version is not the latest one! It's pre-filled with the latest Judgels version that is compatible with the Ubuntu version.
  3. If you generate a different ssh key filename, edit the following variable in env/vars.yml to allow access to root:
    • ansible_ssh_private_key_file
      • Fill with the location of the custom ssh private key file
  4. Run the provision playbook:
    ansible-playbook -e @env/vars.yml playbooks/provision.yml
    This will install the prerequisites packages in the VMs. We only need to do the above playbook once.
  5. (Optional but recommended) Run the optimize playbook:
    ansible-playbook -e @env/vars.yml playbooks/optimize.yml
    This will configure Judgels dependencies (e.g. MySQL, Nginx) with some optimization. We only need to do the above playbook once. It is advised that you actually read the playbook tasks to see what optimization is applied in your system.
  6. Run the deploy playbook:
    ansible-playbook -e @env/vars.yml playbooks/deploy.yml
    This will actually install Judgels. We can rerun this playbook e.g. if we want to deploy new version.
  7. You will notice that there are two new files in your env/ directory: judgels-grader and judgels-grader.pub. These are the keypair used for the graders to retrieve test cases from the server when grading submissions. Please commit these files to your version control as well.

Wait until everything is done. After the playbooks finished, do these verifications:

  1. Verify that we can access the admin web interface at https://admin.mycontest.org.
  2. Verify that we can log in as superadmin, with the password that we just set above.
  3. Verify that we can access the contestant web interface at https://mycontest.org.
  4. Verify that the contestant web interface does not show any error (which means it can successfully access the API server https://api.mycontest.org).

Congratulations, you have just deployed Judgels successfully!

G. Setting up the app identity​

A fresh deployment starts with a placeholder name and home page. To customize them, open the contestant web interface, log in as superadmin, and go to the Admin tab, then System → Settings:

  • App settings: the Name and Slogan shown in the header, and an optional Announcement shown to all users.
  • Home settings: the Banner shown on the home page.

These are stored in the database, so they can be changed at any time without redeploying.

H. Deploying more graders​

If you want to add more graders:

  1. Add/update the IP of the graders under the [grader] section in the hosts.ini file.
    • Let's say that the new IPs are 1.2.3.4 and 5.6.7.8.
  2. Run the provision playbook, only for the new grader VMs:
    ansible-playbook -e @env/vars.yml playbooks/provision.yml --limit=1.2.3.4,5.6.7.8
  3. Run the deploy playbook, only for the new grader VMs:
    ansible-playbook -e @env/vars.yml playbooks/deploy.yml --limit=1.2.3.4,5.6.7.8