Backups

The Backups page (sidebar, Security) backs up this app's own database: on demand, or on a schedule, while the app keeps running. It lists the backups with their time, kind, size and backend version, tests a backup without replacing anything, downloads and uploads backups, and restores one. The page is for admins only, because a backup holds everything the database holds.

What is in a backup, and what is not

A backup is a complete copy of the manager's database at one moment:

users, their roles and server access, password hashes and two-factor secrets,
the server connections, including their WebQuery API keys, Bot Identity and SSH login,
bot flows with their variables and execution history, music bots, songs, playlists, radio stations and request history,
embed widgets, the app's settings, and the logs the app keeps (Change Log, Connection Journal, query console trail, statistics).

Not in it:

the key. The stored credentials and two-factor secrets are encrypted with ENCRYPTION_KEY from the .env (or JWT_SECRET when that is empty). The key is never part of a backup (see below).
the music and video files in the music library. The backup has their entries, not the files; back up the music volume separately if you need it (Deployment).
the YouTube cookie file and the downloaded country database, which can be put back or downloaded again,
the TeamSpeak server itself: its channels, groups and permissions - unless you switch on TeamSpeak snapshots (below), or take one on the Server Maintenance page.

The key

Without the key a backup still restores users, flows and settings, but the stored TeamSpeak credentials, the SSH logins, the music bots' TeamSpeak identities and everybody's two-factor secrets cannot be read. The backend still starts, with those parts switched off (what happens and what to do). Keep the ENCRYPTION_KEY (or JWT_SECRET) somewhere separate from the backups: in a password manager, say, not on the same disk.

The Test button (below) checks whether the running key can read a backup's encrypted values, and the restore asks for a second confirmation when it cannot.

Backing up now

Back up now writes a copy while the app keeps running - music bots keep playing, flows keep running. Before writing, it checks that at least twice the database's size is free on the volume; if not, nothing is written and the page says how much is free and how much is needed. A backup that is cut off half way (the container stopped, the disk filled up) never shows up as a backup; what is left of it is removed by the next run.

Every backup gets a small description next to it: the backend version that wrote it, the database migrations it contains, its checksum and size. The page shows the size of the database and the free space next to the button.

The schedule

Switch on Back up automatically, pick a time and the days. The time is the server's clock, which in a Docker container is usually UTC, not your own time zone; the page shows the server's current time and time zone below the field.

Keep says how many scheduled backups stay (the newest 7 unless you change it); an optional maximum age in days removes older scheduled ones as well. Backups made with Back up now are not counted and stay until you delete them.

When a backup fails - scheduled or not - the page shows a notice with the reason at the top. A failed scheduled run is also written to the Change Log as a change by system.

TeamSpeak snapshots

Switch on Include TeamSpeak snapshots (off by default) and every backup - manual or scheduled - also holds a snapshot of each virtual server of every connection that has WebQuery: settings, channels, groups, permissions and the server's known client identities, not its files. Each server gets its own file, in the format the Server Maintenance page restores. A server that does not answer is noted in the backup's description and the backup goes on without it. The list shows how many snapshots a backup holds; they come with its ZIP (in a folder named after the backup) and are deleted with it.

Restoring a backup on this page only replaces the manager's own database. A TeamSpeak snapshot is put back separately, on the Server Maintenance page, because that changes the TeamSpeak server itself.

Testing a backup

Test checks a backup the way a restore would, on a throwaway copy, without replacing anything:

Integrity: the file is a complete, undamaged database.
Checksum: the file is still exactly what was written (not for the copies taken before an update or an uploaded bare .db, which have no description).
Version: whether this backend can take it. A backup from an older version is fine - the missing migrations would be applied. A backup from a newer version cannot be used by this one. A backup from before versioned migrations cannot be restored from the page (by hand).
Key: a sample of the encrypted values, decrypted with the running key. If any fail, the backup was written with another key.

Downloading

The download arrow gives a ZIP with the database and its description. The download link works once and only for a minute. Every download appears in the Change Log, because a backup contains password hashes and encrypted credentials. Keep downloaded backups as private as the server itself.

Uploading a backup

Choose file on the page takes a ZIP as the page downloads it, or a bare .db file, for example from another installation or one you kept elsewhere. It appears in the list as Uploaded, with the time it was taken when its description came along, and can then be tested and restored like any other. Anything else is refused and leaves nothing behind.

The largest file the page takes is set right below the button (2 GB unless you change it; 4 GB at most). A reverse proxy of your own in front of the manager has its own limit for request sizes, which has to be at least as high, or it refuses the upload before the manager sees it - the page then says so (Deployment). Twice the file's size has to be free on the volume.

Where the backups are

On the backend's data volume, next to the database: the page's own backups in data/backups/managed/, the copies taken before an update one level up in data/backups/. Only the backend's user can read them.

A backup on the volume is gone with the volume. It helps after a mistake or a broken update, not when the disk or the server is lost: download the ones that matter, or include the volume in your server's own backups (Deployment).

Copies taken before an update

Before the backend applies a database migration at start, it takes a copy on its own (Deployment). These copies appear in the list as Before update, with the version that was about to start. They can be tested and downloaded here, but not deleted: their number is set by DB_BACKUP_KEEP. The schedule's rotation and theirs never remove each other's files.

Restoring

The Restore button (the circular arrow) on a backup opens the restore. It runs the same checks as Test and shows what will happen; restoring needs a tick that you understand the current database will be replaced, and a second one if the running key cannot read the backup's credentials (The key). A damaged or changed backup, one from a newer backend version and one from before versioned migrations are refused.

What happens then:

The backend marks the backup and restarts. Until the start applies it, the page shows the marked restore with a Cancel button. Outside Docker, where nothing restarts the backend by itself, start it again yourself.
At the start, the current state is saved first, as a backup of the kind Before restore. That is the way back if the restore was a mistake: restore that one.
The backup takes the database's place in one step, so a start that is cut off half way ends either on the old or on the restored database, never on a mix, and the next start finishes the job.
A backup from an older version is brought up to date by the migrations. If they fail, the state from before is put back automatically and the page says so.
Everybody is signed out - you too - and devices remembered for two-factor sign-in are forgotten, because the sessions of the replaced state must not come back.

Afterwards the page shows how the restore ended and which Before restore backup holds the state from before, and the restored Change Log has an entry for it. If the backend does not start at all, Troubleshooting describes the way by hand.

v0.4, last edited 29.10.2026