Files
Homelab-manager/BACKUP.md
T
bobbanandClaude Sonnet 5.5 ddd0aa622a Settings down to eight tabs; Domains become a tab of DNS
Notifications gains Alert tickets, Display gains Badge colours, and a new Data tab holds Backup,
Logs and Cache. Domains is the 'Domain names' tab of DNS. Old addresses redirect; the docs, the
Privacy page and the links from alerts and the agenda name the new places.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 22:36:24 +02:00

333 lines
18 KiB
Markdown

# Backup and restore
Everything Homelab Manager knows is in **one SQLite file**, plus a handful of settings in your
`.env`. A backup is those two things — and the part people get wrong is keeping them **apart**
(see [Keeping backups safe](#keeping-backups-safe)).
- [The built-in backups (Settings → Data → Backup)](#the-built-in-backups-settings--data--backup)
- [What to back up](#what-to-back-up)
- [Taking a backup](#taking-a-backup)
- [Checking a backup](#checking-a-backup)
- [Before an upgrade](#before-an-upgrade)
- [Keeping backups safe](#keeping-backups-safe)
- [Automating it](#automating-it)
- [Restoring](#restoring)
- [The encrypted export in Settings → Data → Backup](#the-encrypted-export-in-settings--data--backup)
- [If there is no backup](#if-there-is-no-backup)
- [What has been tested, and what hasn't](#what-has-been-tested-and-what-hasnt)
The commands assume the standard Docker setup from the README: you run them in the folder that
holds `docker-compose.yml`, `.env` and `data/`, and the service is called `homelab-manager`.
## The built-in backups (Settings → Data → Backup)
You don't need the snippets below for the everyday case: Homelab Manager takes a backup of its own
database **every day** (03:30 in the notification time zone, the newest 14 kept — both changeable, and it
can be switched off), checks each one as it makes it, and keeps them in `data/backups/` with the same
names the snippets use. **Settings → Data → Backup** shows them and does the rest:
- **Back up now** makes one on the spot. **Download** takes a copy to your computer (the quickest way
off the machine). **Check** opens a backup and says whether SQLite finds it sound, how many users,
servers and integrations it holds, and whether it is from an older or newer version.
- **Upload a backup…** takes a file from somewhere else (another machine, the script below) and keeps it
if it checks out. A file that isn't a Homelab Manager database is refused and nothing is kept.
- **Restore…** checks the backup and *stages* it. Nothing changes until the app next starts — restart it
(`docker compose restart homelab-manager`) and, before anything opens the database, the staged file
takes the database's place. The database that was in use is **kept** in `data/backups/` as
`…-pre-restore.sqlite`, so a restore that wasn't what you wanted is undone by restoring that file. If
something stops it half way, the old database is put back. A backup from a **newer** version than the
one running is refused; an older one is fine (the start-up brings it up to date). **Cancel the restore**
until you restart if you change your mind.
- If the newest backup is more than two days old, or a scheduled one fails, there is an **alert** (and a
message through your channels), and `/metrics` has `homelab_selfbackup_last_success_timestamp_seconds`
for your own monitoring.
Three things it does **not** do, and the rest of this page is about: it does not hold
`CREDENTIALS_ENCRYPTION_KEY` (keep that separately — see [Keeping backups safe](#keeping-backups-safe)),
it does not copy anything off the machine on its own (Download, or copy `data/backups/` with your usual
tool), and it does not replace a restore drill. Access to all of it is for administrators only.
## What to back up
| What | Where | Why | If you lose it |
|---|---|---|---|
| **The database** | `data/homelab-manager.sqlite` | Everything: users and roles, servers and their agent tokens (as hashes), scheduled tasks, secrets, IP addresses, DNS caches, domains, ports, tags, maintenance windows, both logs, settings, the integrations and DNS providers (with their credentials, encrypted), the alert-ticket memory | You start from nothing — see [If there is no backup](#if-there-is-no-backup) |
| **`CREDENTIALS_ENCRYPTION_KEY`** | `.env` | Decrypts every stored credential: integration tokens and passwords, DNS provider credentials, and the Gotify/ntfy/SMTP/webhook credentials | The database restores, but every credential in it is unreadable and has to be entered again |
| **The rest of `.env`** | `.env` | `SESSION_SECRET`, `APP_BASE_URL`, the Authentik client id and secret | `SESSION_SECRET`: everyone has to sign in again, nothing more. The Authentik values can be copied from Authentik again |
| Your `docker-compose.yml` and the image version | next to `.env` | So you can bring it back the way it was. Note which **version** each backup came from (the image tag, or the git commit) | Re-create it from the README |
You do **not** need `data/sessions/` (the sign-ins; everyone just signs in again), the Docker image
(it is rebuilt or pulled), or anything in Authentik, osTicket, Proxmox and the other systems the
app talks to — those have their own backups.
The agents on your servers keep working after a restore: each server's token is stored in the
database, as a hash, and the agent holds the token itself.
## Taking a backup
### Option A — stop, copy, start (simplest)
A few seconds of downtime, nothing to install, and nothing that can go wrong halfway:
```bash
docker compose stop homelab-manager
sudo tar czf ~/homelab-manager-data-$(date +%F-%H%M).tar.gz --exclude=data/sessions --exclude=data/backups data
docker compose start homelab-manager
```
(`sudo` because the container runs as root, so the files in `data/` are root's.)
### Option B — while it runs
Safe to run while the app is working: SQLite makes a consistent snapshot of the file with
`VACUUM INTO`, even if something is writing at that moment. The container has no `sqlite3` tool,
so this uses Node and the library the app already has. The snapshot lands in `data/backups/` on
your host, named with the date and time:
```bash
docker compose exec -T homelab-manager node - <<'EOF'
const fs = require("fs");
const { createClient } = require("@libsql/client");
const dir = "/app/data/backups";
fs.mkdirSync(dir, { recursive: true });
const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-");
const out = `${dir}/homelab-manager-${stamp}.sqlite`;
const c = createClient({ url: "file:/app/data/homelab-manager.sqlite" });
c.execute(`VACUUM INTO '${out}'`).then(
() => { console.log("wrote", out); c.close(); },
(e) => { console.error("backup failed:", e.message); process.exit(1); },
);
EOF
```
It takes well under a second for a database of this size. SQLite will not overwrite an existing
file, which is why the name includes the time; two runs in the same second would collide.
**Which one?** Use B for the regular, automatic backup and A before a risky change if you want
the extra certainty. Either way, the file stays on the same disk as the app until you copy it
somewhere else — see below.
Also copy `.env` — separately from the database (next section):
```bash
cp .env ~/homelab-manager-env-$(date +%F)
chmod 600 ~/homelab-manager-env-$(date +%F)
```
## Checking a backup
A backup you have never opened is a hope, not a backup. This opens the **newest** file in
`data/backups/`, runs SQLite's own integrity check and shows what is in it:
```bash
docker compose exec -T homelab-manager node - <<'EOF'
const fs = require("fs");
const { createClient } = require("@libsql/client");
const dir = "/app/data/backups";
const newest = fs.readdirSync(dir).filter((f) => f.endsWith(".sqlite")).sort().pop();
if (!newest) { console.error("no backups found in", dir); process.exit(1); }
const c = createClient({ url: `file:${dir}/${newest}` });
(async () => {
const one = async (sql) => Object.values((await c.execute(sql)).rows[0])[0];
console.log(newest);
console.log(" integrity check:", await one("PRAGMA integrity_check"));
console.log(" migrations applied:", await one("select count(*) from __drizzle_migrations"));
console.log(" users:", await one("select count(*) from users"), "| servers:", await one("select count(*) from servers"), "| integrations:", await one("select count(*) from integrations"));
c.close();
})();
EOF
```
You want `integrity check: ok` and numbers that look like your system. The migration count is the
version of the database: it goes up by one whenever a release changes the schema.
A tar from Option A is checked by listing it: `tar tzf homelab-manager-data-….tar.gz | head`.
Now and then — say after you first set it up, and after big changes — do a real **restore
drill**: copy a backup to a spare machine or a second folder, start a second instance on another
port with the same `.env`, and sign in. That is the only test that proves the whole chain,
including the key.
## Before an upgrade
Take a backup first, every time. A release can change the database, and the change **only goes
forward**: the new version upgrades the file the first time it starts.
- Restoring an **older** backup into a **newer** version is fine; the newer version brings it
up to date when it starts, and keeps the data.
- Restoring a **newer** backup into an **older** version is **not supported**. The older version
doesn't know the newer tables or columns and may fail in odd ways. If you roll back the
software, roll back the data with it: use the backup you took before the upgrade.
## Keeping backups safe
A database backup holds a lot: the audit log, every server's name and address, the hashed agent
tokens, and all your credentials — encrypted, which is exactly why the key matters.
1. **Keep the key apart from the database.** If the database file and `CREDENTIALS_ENCRYPTION_KEY`
are stolen together, the credentials are readable. Put the database backups where they are
convenient, and the key in a password manager or somewhere else entirely. You need both to
restore a working system, and neither alone is useful to a thief.
2. **Copy it off the machine.** `data/backups/` sits on the same disk as the app, so a dead disk
takes both. Copy the files to another machine, a NAS, or encrypted cloud storage.
3. **Restrict access.** `sudo chmod -R go-rwx data/backups` and the same for wherever you copy to.
4. **Keep a few.** The last 7 daily and 4 weekly is plenty for a system that changes this slowly.
A single backup is not enough: a problem you only notice a week later is already in last night's.
## Automating it
A script that takes the snapshot, keeps the newest 14, and (if you fill it in) copies the newest
off the machine. Save it as `/usr/local/bin/homelab-manager-backup.sh`, make it executable, and
set `APP_DIR`:
```bash
#!/usr/bin/env bash
set -euo pipefail
APP_DIR=/opt/homelab-manager # the folder with docker-compose.yml and data/
KEEP=14
cd "$APP_DIR"
docker compose exec -T homelab-manager node - <<'EOF'
const fs = require("fs");
const { createClient } = require("@libsql/client");
const dir = "/app/data/backups";
fs.mkdirSync(dir, { recursive: true });
const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-");
const out = `${dir}/homelab-manager-${stamp}.sqlite`;
const c = createClient({ url: "file:/app/data/homelab-manager.sqlite" });
c.execute(`VACUUM INTO '${out}'`).then(
() => { console.log("wrote", out); c.close(); },
(e) => { console.error("backup failed:", e.message); process.exit(1); },
);
EOF
# keep the newest $KEEP, delete the older ones (other files in the folder are left alone)
ls -1t data/backups/homelab-manager-*.sqlite | tail -n +$((KEEP + 1)) | xargs -r rm --
# copy the newest one off this machine — edit, or remove if you do that another way
# rsync -a "$(ls -1t data/backups/homelab-manager-*.sqlite | head -1)" backuphost:/backups/homelab-manager/
```
Run it nightly from root's crontab (`sudo crontab -e`):
```
17 3 * * * /usr/local/bin/homelab-manager-backup.sh >> /var/log/homelab-manager-backup.log 2>&1
```
A script that fails quietly is the usual way backups stop. Look at the log now and then, or add
a line that pings something you watch (Uptime Kuma's push monitors are good at this: no ping,
you get told).
## Restoring
You need: a backup of the database, and the `CREDENTIALS_ENCRYPTION_KEY` that was in use when it
was taken (from your `.env` backup).
1. **Stop the app.**
```bash
docker compose stop homelab-manager
```
2. **Keep what is there**, in case the restore isn't what you wanted:
```bash
sudo mv data "data.before-restore-$(date +%F-%H%M)"
mkdir data
```
(If your backups live in `data/backups/`, they are now in the folder you just moved. Take the
one you want from there.)
3. **Put the database in place**, under the name the app expects:
```bash
sudo cp /path/to/homelab-manager-2026-10-07-03-17-00.sqlite data/homelab-manager.sqlite
```
From an Option A tar instead: `sudo tar xzf homelab-manager-data-….tar.gz` in this folder.
4. **Check `.env`.** On the same machine it is probably still right. On a new machine, restore it
from your backup. The one value that must match is `CREDENTIALS_ENCRYPTION_KEY`.
5. **Start it.** The first start brings the database up to the current version by itself.
```bash
docker compose up -d
docker compose logs --tail 30 homelab-manager
curl -fsS http://localhost:3000/health
```
6. **Sign in** and look around: the Servers page should show your servers (as "last seen" at the
time of the backup, until their agents report again, within 15 minutes), and Integrations
should list everything.
### If the key doesn't match
Symptoms: an integration or a DNS provider fails with *"Unsupported state or unable to
authenticate data"*, and notification channels that worked before don't. The database is fine;
only the stored credentials can't be read. If you can't find the old key, enter the credentials
again (Integrations → edit, DNS providers, Settings → Notifications). Nothing else is lost.
**Don't** change `CREDENTIALS_ENCRYPTION_KEY` on a running system to "fix" this: it makes
everything stored so far unreadable.
### After a restore
- Servers whose agents were installed **after** the backup was taken have no token in the
restored database. Press **Rotate token** on that server's row on the Servers page: it shows the new token together with a ready-to-copy install command, to run on that server.
- Anything changed since the backup is gone: new users, edits, audit entries. The audit log will
not show the gap, so it is worth noting it somewhere.
- Everyone has to sign in again if you restored without `data/sessions/`. That is expected.
## The encrypted export in Settings → Data → Backup
A different tool, for a different job. **Settings → Data → Backup** downloads one file, encrypted with a
passphrase you choose (AES-256-GCM, key derived with scrypt), holding:
- the settings (notification channels, display, log retention, alert tickets, and so on),
- the integrations and DNS providers, with their credentials.
Because it is encrypted with your passphrase and not with `CREDENTIALS_ENCRYPTION_KEY`, it is
**portable**: it restores onto a fresh install that has a different key. Importing merges the
settings over the current ones and adds integrations and providers that don't exist yet, matched
by type and name; it never overwrites an existing one.
It does **not** contain servers (and their agent tokens), tasks, secrets, IP addresses, domains,
ports, tags, maintenance windows, the users, or either log. So it is the right thing for moving
your *configuration* to a new instance, or as a second copy of the part that is tedious to
re-enter. It is **not** a backup of the system: use the database backup for that.
Keep the passphrase somewhere safe; it can't be recovered.
## If there is no backup
What you can get back, from least to most work:
- **You have a Settings → Data → Backup export:** a fresh install plus an import restores the settings,
integrations and DNS providers. Everything else is re-created.
- **You only have the `.env`:** a fresh install with the same file works, and everything in the
database starts empty. Sign in (the first account becomes admin), re-add the integrations,
register each server again on the Servers page — it shows a ready-to-copy install command with each
new token — and run that on the server. IP addresses, secrets, domains, ports and tags
are typed in again; DNS records, IPAM syncs and the Tailscale/Proxmox/Docker views come back by
syncing.
- **You have neither:** the same, plus new integration credentials and a new key.
## What has been tested, and what hasn't
**The built-in backups** were tested with the app's own tests (a backup holds what was there and not what came
after; two in the same second don't collide; garbage, someone else's database and a newer version's
database are refused; the newest N are kept; a staged restore is checked, can be cancelled and puts nothing
half-copied in place; a restore that can't complete leaves the database exactly as it was) and by a real
restore: a backup was taken, a user added, the restore staged, the actual built app (`node dist/index.js`)
restarted on the same data folder — the user added after the backup was gone, the previous database was
kept as `…-pre-restore.sqlite`, and the next daily backup was scheduled. **Not** tested: running it inside the
real Docker container, and a very large database (the copy is made on this machine's disk and takes about as
long as copying the file).
The snippet-based way below was tested on a scratch database made with the real migrations:
- The snapshot (`VACUUM INTO`) taken from a second process **while the app was writing**: it
completed in tens of milliseconds, passed the integrity check, held all migrations, and an
encrypted credential in it decrypted with the same key.
- The snippets above, run as written from standard input (`node -`), including a repeat run (which
is why the name has the time in it), the check snippet, and the "keep the newest N" line.
- An **older version's** database restored into the current version: it upgraded itself on start and
kept its data.
- A stored credential with the **wrong** key fails with the message quoted above.
**Not** tested here: running the commands through `docker compose exec` in the real container
(there was no Docker in the test environment — the snippets use only Node and the app's own
database library, which the container has, and the app's working folder `/app` is where `require`
looks), the cron line, the off-machine copy, and a full restore drill on your hardware. Do that
drill once; it is the one check that covers all of them.