InteLIS machine job aids

Job aid 1 of 6

One command runs the machine

Everything on these cards starts the same way.

Open the black terminal window on the InteLIS machine and type:

intelis

A numbered list appears. Type a number, press Enter. Nothing needs to be remembered.

1) Check this machine is working 2) The site will not open — find out why and fix it 3) See whether backups are working 4) Back up now 5) Update InteLIS 6) Restore from a backup 7) Change where backups are sent 8) Quit Type a number and press Enter:

Or type the words, if that is quicker

To do this	Type
Check the machine is working	intelis check
The site will not open	intelis fix-database
Check disk, database and backups now	intelis health
See whether backups are working	intelis backup status
Back up right now	intelis backup
Update InteLIS	intelis update
Restore from a backup	intelis restore
Change where backups go	intelis backup setup

How often

When	What
Every Monday	Check backups are working (menu 3). Takes ten seconds.
When asked to	Update InteLIS (menu 5).
When something looks wrong	Check the machine (menu 1) before calling anyone.
When the site will not open	Repair the database (menu 2). It asks before changing anything.
Never, normally	Back up by hand. The machine backs itself up every 8 hours.

Never type sudo in front of intelis It asks for administrator rights itself, only for the steps that need them, and only then does it ask for the password. Adding sudo is not needed and for some commands makes things worse, because it runs work as the administrator that is supposed to run as the account InteLIS itself uses.

If typing intelis says "command not found"

The machine is an older installation. Run the update once using the long command on card 3, and the short one works from then on.

Job aid 2 of 6

Install InteLIS on a new machine

A machine with Ubuntu on it and nothing else.

Before starting

Ubuntu installed	Ubuntu 22.04 or newer
Internet	Needed for the whole install. It downloads a lot.
Administrator password	The one used to log in to the machine
Time	Allow an hour. Do not start it ten minutes before leaving.

Restoring an old lab onto a new machine? Do not use this card. Go to card 5 and run the restore first. It prints the exact install command, with the backup already attached, so the machine comes back with its data instead of empty.

Type these three lines, one at a time

cd ~

wget -O setup.sh "https://raw.githubusercontent.com/deforay/intelis/master/scripts/setup.sh?v=$(date +%s)"

sudo bash setup.sh

Download the file first, always Never join these into one line that pipes the download straight into the shell. The installer asks questions, and a piped run answers them with its own text. It refuses to start that way, on purpose.

What it will ask

Question	Answer
Where to install	Press Enter for the standard place unless told otherwise
Database password	Choose one and write it down somewhere safe. It cannot be recovered.
STS address	The address given by the programme. Leave empty for a standalone lab.
Which modules	The tests this lab does

When it finishes

Type intelis check. Every line should say PASS.
Open a browser on the machine and log in.
Set up backups straight away, using card 4. A machine with no backup is one disk away from losing everything.

Job aid 3 of 6

Update InteLIS

Do this when the programme asks for it.

Once per machine, the first time only

This brings the machine's own commands up to date. Skip it if the machine has already had it done.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/deforay/intelis/master/scripts/bootstrap.sh)"

Every time after that

intelis update

That is the whole procedure. Leave the window open until it finishes and says so.

What happens while it runs

1Downloads the new version

2Takes a snapshot it can go back to

3Puts the new files in place

4Updates the database

5Restarts the web server

Before and after

Before	Tell the lab. There is a short spell where pages may not load.
Before	Check backups are current: intelis backup status
After	Run intelis check. Every line should say PASS.
After	Log in and open one page, to see it with your own eyes.

Do not close the window, unplug, or restart An update interrupted halfway leaves new code running against an old database. If the window is closed by accident, run the same command again rather than anything else. It is safe to re-run.

If it fails

The update keeps a snapshot and reports what went wrong. Do not try to fix the machine by hand. Run intelis check, and send the whole output to support.

Job aid 4 of 6

Backups

Set it up once. Check it every week.

Setting it up, once per machine

intelis backup setup

It asks where backups should go, and tests the connection before saving anything:

1 — Another Linux machine	Over the network. Needs that machine's address, a username, and its password once.
2 — A Windows shared folder	Share a folder on the Windows PC first, and give the user Change permission on it.
3 — A USB or external drive	Plug it in first. Simplest, but someone has to keep the drive safe.

It then runs the first backup while you watch. If that fails, it says so rather than pretending it worked.

After that it runs itself

Every 8 hours, and after every restart. Nobody has to remember.

The weekly ten seconds

intelis backup status

Lab : kigali-central (kigali-central-a1b2c3d4) Backing up to : backup@192.168.1.20:/home/backup/backups/... Last good backup: 2026-08-13T04:00:11Z (6 hours ago) Size on backup : 4.2G Last attempt : succeeded in 143s Schedule : every 8 hours and after every restart

What it says	What to do
Last good backup: a few hours ago	Nothing. This is what right looks like.
Last good backup: never	It has never worked. Run intelis backup test.
More than a day old	Run intelis backup test to find out why.
Last attempt: FAILED	Read the reason on the next line. Usually the other machine is switched off.
Schedule: OFF	Backups are not scheduled. Call support.

The other two commands

intelis backup test	Checks the connection and reports what would be copied. Changes nothing. Safe any time.
intelis backup	Backs up right now, on this machine and off it. Use before an update or a move.

A backup nobody has ever restored is not a backup It is a hope. Once a year, restore one onto a spare machine and check the data is there. Card 5 is how.

Job aid 5 of 6

Restore from a backup

For a machine that has died, or data that has been lost.

Stop and think first Restoring replaces the current data with older data. Anything entered since that backup was taken is gone. If the machine still works, call support before restoring.

See what backups exist

intelis restore --list

Restore one

intelis restore

It connects to wherever backups were sent, shows every lab stored there, copies the chosen one back, and checks the files are readable before doing anything with them.

What happens next depends on the machine

Situation	What it does
InteLIS is installed and working	Offers to restore the database in place. It takes a safety copy of the current data first, so this can be undone.
The machine is blank or newly rebuilt	Prints one command that installs InteLIS and loads the backup in the same step. Copy that line and run it.

Rebuilding a machine that died completely

Install Ubuntu on the new machine.
Connect it to the same network as the backup destination, or plug in the backup drive.
Run intelis restore and choose the lab.
Copy the command it prints, and run it. Allow an hour.
Run intelis check, then log in and confirm the data is there.
Set backups up again with card 4. The new machine is not backing anything up yet.

If the backups are encrypted The command it prints is enough when the new machine uses the same database password as the old one. If it does not, the STS administrator has to issue a recovery token first. Ask for one before starting, not halfway through.

Job aid 6 of 6

When something is wrong

Do this before calling anyone. It often answers the question.

intelis check

It examines the machine and prints one line per thing checked. It works even when InteLIS itself will not start, which is exactly when it is needed.

PASS PHP version 8.4.5 PASS Database host localhost WARN Apache post_max_size 8M — large imports will be truncated FAIL Schema version database is at 5.6.3, migrations go to 5.6.5 run: intelis migrate

Reading it

PASS	Fine. Ignore.
WARN	Works, but something will bite later. Worth reporting.
FAIL	Broken. This is the line that matters.
The indented line	The exact command that fixes it. Type it as printed.

The other check

intelis health

Disk space, database speed, and whether backups are current. Use this one when the machine works but feels slow or full.

Common ones

Sign	Likely cause
Pages blank or will not load	Run intelis check. Usually an interrupted update or a stopped database.
Disk usage above 90%	The disk is filling. Call support before it reaches 100%, not after.
Everything is slow	Run intelis health and report the database latency figure.
Results not reaching the programme	Check the STS address and token lines in intelis check.

When calling support, send the output Run intelis check, select all the text in the window, copy it, and send it. It answers most of the questions support would otherwise have to ask, and it turns a two-day exchange into one message.

What not to do

Do not reinstall to fix a problem. Restoring after an unnecessary reinstall loses everything entered since the last backup.
Do not delete files to free disk space. Ask first.
Do not run commands found on the internet. Run the one InteLIS printed.