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 app is designed to be hosted 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](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-22-04).

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

- [Install on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) or [Install on Debian](https://docs.docker.com/engine/install/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.

```sh
# .env

SERVER_NAME= # URL where this will be hosted.
```

```sh
# 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:

```sh
# 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 four for the www version (remember to keep the www. prefix where present):

```nginx
# 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.

```sh
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](https://opendyslexic.org/), 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.

## Updating the Installation

If the app is updated, you can update the version on your installation using the following method:

### Navigate to the root folder

This will be the root folder into which you cloned the git repository when you set the app up.

### Stash your local changes

When you update the code, there is a risk the changes you made to your configuration will be overwritten.
To avoid this, use the following command:

```git stash```

This will stash the changes you made, and we can re-apply the changes once the new code has been downloaded.
If you do not have any other changes stashed, the index number of these changes should be `0` in a later step.
If there are other changes, make sure to note what the correct index number for the stashed changes is.

### Take down the Docker containers

We will need to stop the current containers with the following command:

```sudo docker compose down```

This may take a few seconds.

### Pull the updated code

Download the updated code from the Git repository:

```git pull```

This step might fail if you have any un-stashed local changed.

### Re-Apply your local configurations

Because we stashed our local configurations, we can re-apply them once again:

```git stash pop 0```

The index number (`0`) is assuming there were no other changes saved on your git repository.
If you have a different index number for the relevant changes from the above step, change this accordingly.

### Re-build the docker image

Now that we have the base code downloaded, we just need to update the docker image:

```sudo docker compose build app```

### Re-build the containers

This is the same last step as running the containers in the last step of the installation:

```sudo docker compose up -d```