ska-referee-test/README.md

SKA Referee Test App

About

A web app that digitises the theory exam for the Scottish Korfball Association referee qualification

This web app provides an on-line platform through which to administer and take the SKA Refereeing theory exam. The app includes a digital client to take the exam for candidates, as well as an admin console from which to manage tests, view results, and update questions. The exam client is made with accessibility in mind, and has been designed to be adaptable to dyslexia and other learning needs or cognitive needs.

Set Up and Installation

The clien is designed to work on a server.

Pre-Requisites

• A Debian- or Ubuntu-based server, preferably the latest distribution.
• Docker (specifically, Docker Engine)
• Docker Compose
• Git

Installation

Install all the pre-requisites

The first step is to ensure all the prerequisites are available on the server.

To set up the server, consult some of the comprehensive guides on various hosting platforms like Linode or DigitalOcean. Here is a good starting point on setting up a server.

To install Docker and Docker Compose, consult the respective documentation:

• Install on Ubuntu or Install on Debian
• Docker Compose should be installed as part of that.

At the time of writing, there has been an upgrade to Docker and Docker Compose, meaning the syntax below might be different between versions.

Check if Git is installed on your server using the git --version command. If it isn't installed, install it. This should normally come pre-packaged with your OS distribution. But if it doesn't, look up how to for whatever OS you use. If you are using Ubuntu or Debian, it should be as easy as using the command:

$ sudo apt-get install git -y

Preliminary Set-Up: Clone repos and Configure Values

Open a terminal and navigate to the folder where you want to install this app. I would suggest using a subfolder within your Home folder:

$ cd ~ && mkdir ska-referee-test && cd ska-referee-test

That way, you will ensure you can read and write all the necessary files during installation. Once in the destination folder, clone all the relevant files you will need for the installation:

$ git clone https://git.vsnt.uk/viveksantayana/ska-referee-test.git .

(Remember to include the trailing dot at the end, as that indicates to Git to download the files in the current directory.)

Populate Environment Variables

Configuration values for the app are stored in the environment variables file. To set it up, make a copy of the example file and populate it with appropriate values.

$ cp .env.example .env

Make sure to use complex, secure strings for passwords. Also make sure that the various entries for usernames and passwords match.

Input Specific Values for Your Installation

There are some values in the following four files you will need to configure to reflect the domain you are installing this app.

# .env

SERVER_NAME= # URL where this will be hosted.

# install-script.sh

domains=(example.org www.example.org)
email="" # Adding a valid address is strongly recommended

Substitute the domain name domain_name in the two file paths in the following file:

# nginx/ssl.conf

ssl_certificate /etc/letsencrypt/live/domain_name/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/domain_name/privkey.pem;
...

And six locations in the following file, two for the regular version of the domain and two for the www version:

# nginx/conf.d/ref-test-app.conf

server {
    server_name domain_name;
    listen 80 default_server;
    ...
}

server {
    server_name domain_name;
    listen 443 ssl http2 default_server;
    ...
}

server {
    server_name www.domain_name;
    listen 80;
    listen [::]:80;
    # Redirect to non-www
    return 301 $scheme://domain_name$request_uri;
    ...
}

server {
    server_name www.domain_name;
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    ...

    # Redirect to non-www
    return 301 $scheme://domain_name$request_uri;
}

Installing SSL Certificates

The app will use SSL certificates to operate through a secure, https connection. This will be set up automatically. However, there is a specific chicken-and-egg problem as the web server, Nginx, won't run without certificates, Certbot, the certificate generator, won't run without the web server. So to solve this, there is an automation script we can run that will set up a dummy certificate and then issue the appropriate certificates for us.

$ chmod +x install-script.sh
$ sudo ./install-script.sh

This will take a long time to run the first time because it will try and generate a fairly sizeable cypher.

When we later run the server, Certbot will check for renewals of the SSL certificates every 12 hours, and Nginx will reload the configurations every 6 hours, to make sure everything runs smoothly and stays live.

Run the Stack

Everything should be good to run on autopilot at this point. Navigate to the root folder of the app, the folder where you have install-script.sh and docker-compose.yml. Run the following command:

sudo docker compose up -d

And you should have the stack running. You can register in the app and begin using it.

Fonts

The app uses OpenDyslexic, which is available on-line. It also has the option of rendering in other system fonts, but this can vary depending on your operating system. Because these are proprietary fonts, they cannot be made available on-line in the same way as open source ones should your system not have them. Some fonts may not display correctly as a result.