Setting up the exam server

This is done once per school, by whoever set up the machine. Allow an hour the first time, most of it waiting for downloads.

What you needCopy Anchor Link

• A computer to be the exam server. An ordinary desktop is enough for a few hundred students: 4 CPU cores, 8 GB of memory, and a disk with 50 GB free. It stays in the ICT hall, wired to the same switch as the hall machines.
• Ubuntu Server 24.04 installed on it, with a name and password you know.
• A network cable, not Wi-Fi, for the server itself.
• The deploy folder from openCBT, and the access token your supplier gave you. Keep the token safe: it is what lets this machine fetch openCBT.
• Internet on the server for the setup only. Once running, the hall works with the internet unplugged.

1. Install DockerCopy Anchor Link

Sign in to the server and run:

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker $USER

Sign out and back in, so the last line takes effect. Check it worked:

docker run --rm hello-world

You should see a short "Hello from Docker!" message.

2. Put openCBT's files on the serverCopy Anchor Link

Copy the deploy folder to the server, into your home directory. If it is on a flash drive, copy it with the file manager; if you are working over the network, scp it. You should end up with:

~/deploy/compose.onsite.yml
~/deploy/onsite.env.example
~/deploy/scripts/

3. Sign in to the software storeCopy Anchor Link

Once per machine, with the token from your supplier:

cd ~/deploy
docker login ghcr.io -u YOUR-GITHUB-USERNAME

Paste the token when it asks for a password. Nothing is shown while you type; that is normal. You should see Login Succeeded.

4. Fill in the settingsCopy Anchor Link

cp onsite.env.example .env
nano .env

Three lines must be filled in:

Save with Ctrl+O, Enter, then Ctrl+X.

5. Start itCopy Anchor Link

docker compose -f compose.onsite.yml up -d

The first run downloads openCBT, which takes a few minutes on a school connection. When it finishes, check it:

docker compose -f compose.onsite.yml ps

app and db should both say healthy, and worker should say Up.

6. Find the server's addressCopy Anchor Link

hostname -I

The first number, something like 192.168.0.10, is the server's address on your network. Write it on a card and tape it to the machine; the hall needs it every exam day.

7. First sign-inCopy Anchor Link

On any hall machine, open a browser and type the address — just the number, no http:// and no port:

192.168.0.10

Sign in with principal and the SUPER_ADMIN_PASSWORD you chose.

8. Set up your schoolCopy Anchor Link

The first sign-in opens a setup page before anything else. It asks for three things:

• The school's name, as it should appear on sign-in pages and printed results.
• The logo, if you have the file to hand. You can add or change it later in Settings.
• A new password for yourself. The one you just used sits in plain text in a file on the server, so openCBT will not let you keep it. Choose one only you know, at least 8 characters, and write it down somewhere safe.

Press Finish setup. From then on, principal signs in with the new password — the one in the .env file no longer works.

9. Fill in the schoolCopy Anchor Link

Then, in this order:

1. Organisation — add your faculties and departments.
2. People — add staff, and import your students from a spreadsheet. Make a super admin account in your own name, and keep principal for emergencies.
3. Courses — create the session and its courses, and enrol students.

Each page explains what it needs as you go.

Keeping the address the sameCopy Anchor Link

The server's address must not change, or the hall machines will not find it after a reboot. Ask whoever manages your network to reserve that address for this machine (a "static lease" for its MAC address). Your supplier's webmaster guide covers this if you do it yourself.

What nowCopy Anchor Link

• An exam day — the routine before and after papers.
• Backups — do this from the first exam onwards.