Code Docs

ARBITRE Docs

Running Arbitre locally

Creating the Keycloak instance

Arbitre uses Keycloak to manage authentication. To have Arbitre running on your machine, you need to install and setup a Keycloak instance.

Running Keycloak

Start by downloading Docker on your machine.

Launch Keycloak by running :

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 start-dev

Keycloak can then be accessed at http://localhost:8080.

Setting up the Keycloak client

Log in as an admin to the administration console.

Keycloak client

Go to “Clients” and create a client with the following parameters :

• Client type : “OpenID connect”
• Client ID : arbitre (the other settings are optional)

Client settings

In the client settings, under Access Settings, configure as follows :

• Root URL : http://localhost:3000
• Home URL : http://localhost:3000
• Valid redirect URIs : http://localhost:3000/*
• Valid post logout redirect URIs : +
• Web origins : +
• Admin URL : leave empty

Roles

On the left side menu, go to “Realm roles”. Create a new role.

• Role name : teacher ⚠️ Lower case matters here.

This is the way Arbitre knows what users are teachers, so they can create courses.

Users

Go to “Users” and click “Add User”. Give the user an username and an email address. The email is mandatory for Django to interact with Keycloak.

Once the user is created, click on the user, go to the “Credentials” tab, and click “Set password”. Choose a password. You can safely uncheck “Temporary password”.

It is recommended to create both a regular user and a teacher user.

Creating a teacher user

To give an user the teacher role, click on the user, go to the “Role mapping” tab, click “Assign role”, and select “teacher”.

⚠️ If you close the terminal Keycloak is running in, the Keycloak instance will be stopped.

Using Docker Desktop, you can then re-start the Keycloak container without having to do the whole configuration again.

Setting up the worker server

The worker server is the server that runs the code sent by students, and that returns test results to Arbitre.

It uses Judge0 CE. Follow these instructions to install and run it : https://github.com/judge0/judge0/blob/master/CHANGELOG.md#deployment-procedure

Setting up the database

Arbitre uses PostgreSQL as its database.

Installing PostgreSQL

Install PostgreSQL on : * Windows * macOS * Ubuntu and other Linux distributions

Make sure to create an admin user.

Creating a database

Using the preferred method for your operating system (see former tutorials), create a PostgreSQL database called ‘arbitre’.

Cloning the project

git clone <https://github.com/paulglx/arbitre>

Setting up environment variables

Create a backend/arbitre/.env file and fill in the variables following the example in backend/arbitre/.env.example.

Do the same thing in frontend/.env

Running Arbitre

Arbitre uses the Nix package manager to manage dependencies and to provide a development environment.

Installing the Nix package manager

sh <(curl -L <https://nixos.org/nix/install>) --daemon # remove '--daemon' for macOS

For more information, see the official Nix website

Entering the development environment

export NIXPKGS_ALLOW_BROKEN=1; nix develop --impure

Installing dependencies and setting up frontend and backend

./setup.sh

Running the application

./run.sh