InteLIS machine job aids

Six single-page cards for whoever looks after the machine. Print and keep near it.

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 thisType
Check the machine is workingintelis check
The site will not openintelis doctor
Check disk, database and backups nowintelis health
See whether backups are workingintelis backup status
Back up right nowintelis backup
Update InteLISintelis update
Restore from a backupintelis restore
Change where backups gointelis backup setup

How often

WhenWhat
Every MondayCheck backups are working (menu 3). Takes ten seconds.
When asked toUpdate InteLIS (menu 5).
When something looks wrongCheck the machine (menu 1) before calling anyone.
When the site will not openFind out why and fix it (menu 2). It asks before changing anything.
Never, normallyBack 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. Adding sudo runs work as the administrator that must run as the account InteLIS uses, and that breaks some commands.

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 installedUbuntu 24.04 LTS or newer
InternetNeeded for the whole install. It downloads a lot.
Administrator passwordThe one used to log in to the machine
TimeAllow an hour. Do not start it ten minutes before leaving.
Restoring an old lab onto a new machine? Do not use this card. Use card 5. It installs InteLIS and loads the backup in one step, 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 asks

QuestionAnswer
Installation directoryPress Enter for the standard place unless told otherwise
What is this machine?Lab machine (LIS)
Remote STS URLThe address given by the programme. Leave empty for a standalone lab.
New MySQL root passwordChoose one, type it twice, and write it down somewhere safe. It cannot be recovered.

When it finishes

  1. Type intelis check. No line should say FAIL.
  2. Open a browser on the machine and log in.
  3. 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

BeforeTell the lab. There is a short spell where pages may not load.
BeforeCheck backups are current: intelis backup status
AfterRun intelis check. No line should say FAIL.
AfterLog in and open one page, to confirm it works.
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:

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

It then runs the first backup on screen. 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 History : 2026-07-15 to 2026-08-13 (30 days) Last attempt : succeeded in 143s Schedule : every 8 hours and after every restart
What it saysWhat to do
Last good backup: a few hours agoNothing. This is what right looks like.
Last good backup: neverIt has never worked. Run intelis backup test.
More than a day oldRun intelis backup test to find out why.
Last attempt: FAILEDRead the reason on the next line. Usually the other machine is switched off.
Schedule: OFFBackups are not scheduled. Run intelis backup enable.

The other two commands

intelis backup testChecks the connection and reports what would be copied. Changes nothing. Safe any time.
intelis backupBacks 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.

InteLIS still runs on this machine

intelis restore

It connects to wherever backups were sent, copies the chosen lab back, and checks the files are readable. It then offers to restore the database in place, after a safety copy of the current data. To only see what backups exist, type intelis restore --list.

Rebuilding a machine that died

The intelis command does not exist on a new machine yet. Use one of these routes instead.

  1. Install Ubuntu 24.04 LTS or newer on the new machine, and connect it to the internet.
  2. Start setup with the backups, by the route that matches where they are.
    A copy of the old backups folder on a USB drive. Plug it in and type:
    cd ~ && wget -O setup.sh "https://raw.githubusercontent.com/deforay/intelis/master/scripts/setup.sh?v=$(date +%s)"
    sudo bash setup.sh --restore-from-backup-folder
    Before pressing Enter, type a space and drag the backups folder onto the terminal window.
    Backups sent to another Linux machine, a Windows share or a backup drive. Type:
    cd ~ && wget -O restore-backup.sh https://raw.githubusercontent.com/deforay/intelis/master/scripts/restore-backup.sh
    sudo bash restore-backup.sh
    Choose the lab, then Just the database backups. Copy the command it prints at the end, and run it.
  3. Answer setup: Lab machine (LIS), the old STS address, and a new MySQL root password. Wait for Setup complete.
  4. Log in with an administrator account from the old machine, and confirm the data is there.
  5. Set backups up again with card 4. The new machine is not backing anything up yet.
If setup stops with "Failed to decrypt" Setup reads the key from the config folder copied with the backups. Without it, the STS administrator has to issue a one-time recovery token. Run the same setup command again, adding --sts-url and --recovery-token with the values given.
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

PASSFine. Ignore.
WARNWorks, but causes trouble later. Worth reporting.
FAILBroken. This is the line that matters.
The indented lineThe 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

SignLikely cause
Pages blank or will not loadRun intelis doctor. It finds the cause and offers to fix it. Usually an interrupted update or a stopped database.
The database will not startRun intelis fix-database. It asks before changing anything.
Disk usage above 90%The disk is filling. Call support before it reaches 100%, not after.
Everything is slowRun intelis health and report the database latency figure.
Results not reaching the programmeCheck 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