Backups and upgrades
Two habits keep an install safe: a backup every night, and upgrades done with the one command that takes a backup first. Every command here is run in the ServiceFlo folder on the server.
What holds your data
| Where | What is in it |
|---|---|
| The database | Every ticket, guide, person and setting. |
| The uploads | Files people attached, and pictures in guides. |
.env |
Your settings and secrets. |
The first two live in Docker volumes (storage Docker keeps outside the containers), so stopping, starting, rebuilding and upgrading never touch them.
Taking a backup
make backup
It makes one folder, backups/<date_time>/, holding the database
(database.dump), the uploads (media.tgz) and a note of when it was taken and from
which version (info.txt). The site keeps running meanwhile. The command checks its
own work and removes the folder if anything failed, so a folder that exists is a
backup that worked. The newest 7 are kept; make backup KEEP=30 keeps more.
Three things the command cannot do for you:
-
Run every night. Use cron, the scheduler built into Linux. Run
crontab -eand add this line (with your own folder) for a backup at 01:30 each night:30 1 * * * cd /srv/serviceflo && make backup >> backups/backup.log 2>&1 -
Leave the server. A backup on the same disk is lost with that disk. Copy the
backups/folder somewhere else after it runs: another server, or cloud storage. -
Include
.env. It is left out because it holds secrets. Keep your own copy. Without itsFIELD_ENCRYPTION_KEYS, the stored mailbox passwords cannot be read, even from a perfect backup.
Putting a backup back
make restore BACKUP=backups/<date_time>
This replaces everything in the install with what the backup holds, so it asks you
to type restore first. It then takes a backup of what is there now (in case you
change your mind), stops the site, loads the database and puts the uploads back. It
leaves the site stopped. Start it with:
make prod-up
Try this once before you need it. On a spare machine: copy a backup folder and your
.env there, start only the database
(docker compose -f docker-compose.prod.yml up -d --wait postgres), then
make restore and make prod-up, and sign in.
Upgrading
-
Read the upgrade notes.
CHANGELOG.mdhas a section per release, each with Upgrade notes. Read the notes of every release between yours and the one you are moving to. Most say “Nothing to do by hand.” -
Run the upgrade. To move to a named release (recommended):
git fetch --tags git checkout v0.1.0a2 make upgrade PULL=noOr, to follow the newest code:
make upgrade.
The command does four things in order, and stops at the first that fails:
- Takes a backup, into
backups/<date_time>_before-upgrade/. - Gets and builds the new version. The site keeps running the old one meanwhile.
- Stops the site and updates the database to the new version’s shape. Your data stays; only its layout changes.
- Starts the site and waits until it answers.
Expect a few minutes during which the site is down (parts 3 and 4).
If an upgrade stops
Read the message: it says which part failed.
-
Part 1 or 2 failed (the backup, the download or the build). Nothing has changed and the old version is still running. Fix the cause (a full disk, no internet) and run the upgrade again.
-
Part 3 or 4 failed (the database update, or the new version does not start). Go back to where you were. The command prints these three lines with the real names filled in:
git checkout <the version you had> make restore BACKUP=backups/<date_time>_before-upgrade make prod-up
Never go back by checking out older code alone. Older code does not understand a database a newer version has changed, and ServiceFlo refuses to start that way. Always restore the backup that belongs with it.
Which version am I running?
Sign in as a superuser and open Settings › Installation › Version. It shows the running version, since when, and every upgrade the install has been through.
From the terminal:
docker compose -f docker-compose.prod.yml run --rm web record_version
What deletes data
Only these, and none of them is part of normal running:
docker compose -f docker-compose.prod.yml down -v. The-vremoves the volumes.downwithout it is safe.docker volume rmanddocker volume prune.make restore, which replaces the data with the backup’s (after taking a backup of its own).
More detail on all of this is in deployment.md, under “Upgrading” and “Backups”.