Backups in the app
Settings, Backups (/admin/backups). Needs module.backups. Viewing settings
and history requires backup.view; changes, downloads and restores require
backup.manage.
The application takes its own encrypted, scheduled backups. On managed hosting each one is copied offsite for you; on a deployment you run yourself, getting them off the machine is yours.
Whole-school access and archive compatibility
Section titled “Whole-school access and archive compatibility”These rules apply from 0.12.0.
Backups contain every campus and department in one school. Campus-limited
accounts cannot view or operate them. Once any department is configured,
including a paused department, the account also needs departments.manage.
Membership in several departments does not substitute for that permission.
ICT-only schools with no configured departments retain their existing backup
permissions, provided the account has unrestricted campus access.
New logical archives use format v3, recording unrestricted campus and department scope. The snapshot includes active and paused desks, their tickets, service answers and original question labels, history, attachments stored in the database, membership, schedules, rules and role assignments.
The in-app restore accepts a complete v3 archive for the same school and platform schema. It refuses missing tables, inconsistent row counts or missing relationship links before replacing data. A format v1/v2 archive, including one from an ICT-only school, can still be downloaded and checked for integrity, but cannot be restored from this screen: its completeness was not recorded. Keep those archives and their encryption keys. An operator must validate them against the matching release in an isolated restore drill and plan a maintenance restore. Do not edit a manifest to bypass this check.
A successful restore keeps paused departments paused. If restoring data fails, the database transaction rolls back; existing data and pause settings remain. Existing audit entries are retained and a successful restore adds its own entry. A Verified result checks readability and integrity; it does not override restore compatibility checks or replace a restore drill.
The page
Section titled “The page”The line under the title says when the next scheduled run is, or that scheduled backups are off, and Back up now runs one straight away. If the latest run failed, a warning at the top says when and why.
Recovery evidence is read from recorded runs:
| Row | What it says |
|---|---|
| Last successful backup | When, how big, and what kind: its scope, its format and what started it |
| Verification | When a backup was last read back and decrypted, and how many successful runs are verified |
| Offsite copy | Whether the last successful run has an offsite copy recorded, and the result of the last storage check |
| Encryption key | The SECRETS_MASTER_KEY that seals every backup. No backup restores without it |
Schedule and storage holds the settings, saved together with Save schedule:
- Scheduled backups: Run on the schedule below.
- Runs: the frequency in words, Every few minutes, Every hour, Every day, Every week or Every month, in server time. Cron sits underneath and is still available as Custom (cron), and any expression the picker cannot put into words forces Custom on, so you read the expression itself instead of an approximation of it.
- Format, Target directory, Keep for (days) and Keep at most (backups).
- Alert on failure: Raise a desk alert when a scheduled run fails.
- Integration hooks: a webhook before and after each run, behind Set webhooks. The post-backup webhook is sent a JSON result, so Velero, Restic or cron can drive or react to a run.
Run history lists each run with its status, start, scope, size, whether it is verified and whether an offsite copy is recorded. Each run offers Verify until it is verified, then Download; its menu has Verify again, Restore… for a backup that can be restored here, and Delete….
Restore and export:
- Restore replaces this school’s data with one portable backup of this school alone, in one transaction, once you type the school’s short name. Anything created after that backup is lost.
- Database dumps are restored by hand on the server, in a maintenance window. A dump replaces every school on the server at once.
- Export this school’s data downloads a portable, unencrypted JSON bundle. See portable export.
- Check offsite storage writes a small test file to the offsite bucket, reads it back and removes it.
- Bring back offsite backups, for after a rebuild. See after a rebuild.
The one rule
Section titled “The one rule”SECRETS_MASTER_KEY must be backed up somewhere that is not the server it
protects.
Backups are encrypted with it. A backup cannot be restored without that key.
If you instead restore a separate SQL dump or portable export, the database records may return while their connector credentials remain unreadable. Those credentials then require the original key or reconfiguration.
Put a copy in a password manager. Not in a file next to the backup, and not in the same cloud account.
Storage across updates
Section titled “Storage across updates”From 0.12.0, Docker deployments use a dedicated volume mounted at
/app/backups for application archives. Its updater inventories every school’s
configured path, including inactive schools, before replacing an existing API
container. It migrates default-path archives from the old container and refuses
unmounted or read-only custom paths. A successful migration does not create an
off-site copy.
Native updates preserve archives under server/backups when swapping
program directories. Custom paths within replaceable program directories need
an operator migration; move them to persistent storage before updating. An older
installed updater does not acquire new behaviour until it has itself been updated.
See updating.
Retention
Section titled “Retention”Set it. Keep for takes days and Keep at most takes a number of backups; 0 in either keeps everything. With both at 0, backups accumulate until the disk fills, and a full disk stops the database and then the backups.
Balance how far back you might need against how much disk you have. Nightly for a fortnight plus weekly for a term suits most schools.
Verification
Section titled “Verification”Verifying reads a backup back and checks it. Do it regularly, and schedule it if you can.
Verification is not the same as a restore drill. Verification proves the file is intact. A restore drill proves your process works. See backups and restore.
When one fails
Section titled “When one fails”When Alert on failure is ticked, a desk alert is raised and the backup.failed
email is sent if email is configured. The email
template itself cannot be disabled. Recipients must have backup management permission, unrestricted campus
access and, when departments exist, school-wide department administration.
Backup toasts use the corresponding viewing permission and the same scope rules.
The usual causes, in order:
- Disk full.
- Retention not pruning, so the disk filled.
- Permissions, after somebody changed the service account.
- The database was unreachable at that moment.
Run one on demand once you have fixed it, rather than waiting for the schedule to prove the fix.
What a backup contains
Section titled “What a backup contains”| Included | Not included |
|---|---|
| Every database table for the tenant | The master key itself |
| Encrypted connector credentials | Files in external object storage |
| Configuration, roles, workflow, templates | The application binaries |
| Audit log, within retention |
If you use external S3 for logos, photos and exports, back that bucket separately.
Portable export
Section titled “Portable export”Exports a per-tenant copy you can take elsewhere. It is a normal feature rather than a support request, which matters on managed hosting: getting your data out does not require anybody’s cooperation.
The portable export is compressed JSON, not an encrypted archive. Store and
transfer it as sensitive school data. Connector credentials inside it remain
encrypted, so recovering those credentials elsewhere needs the matching keyring.
Use a backup run’s Download action for the encrypted .pbk archive.
After a rebuild
Section titled “After a rebuild”A deployment rebuilt on a fresh server starts with an empty run history, so there is nothing to restore from until its offsite archives are back. Bring back offsite backups lists this school’s archives in offsite storage, downloads each one whose name this server would have written, checks it against the checksum it was uploaded with, and records it as a run you can verify and restore. An archive that fails either check is listed as refused, and one already in the run history is left as it is. Verify one before you restore it.
It needs backup.manage, works while the desk is read-only, and is recorded in
the audit log as Offsite backups imported.
Managed hosting
Section titled “Managed hosting”From its first boot, a managed deployment has scheduled backups on: every night at 03:00, kept for 90 days, each copied to an offsite bucket of its own. Turning them on is recorded in the audit log as Managed backup defaults applied. Settings an administrator has saved are never changed by this, and self-hosted deployments keep their own defaults.
This screen works the same on managed hosting, and the portable export is still yours to run whenever you like. To have us restore a backup, see support, restores and exits.
Permissions
Section titled “Permissions”| Permission | Allows |
|---|---|
backup.view | See backup settings and history |
backup.manage | Schedule, run, verify, download, export, delete and restore |