Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Backups and restore

Make a backup on demand, know what the nightly backup keeps, and restore one, including the password and key steps that follow a restore.

For
Owner
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

Pop Dispatch makes a backup every night and whenever you ask. You will be able to make a backup, read the list, and know exactly what to do after a restore.

Before you start #

Backups belong to the owner. Other roles receive "Only the owner can use backups."

Make and read backups #

The Backups step of setup with the Make a backup file now button and the line that says the file was made and checked.
The backup button as it appears in setup, with the checked result.
  1. Open Settings, Backup. The list shows each backup with its kind (nightly, on demand, before update or before restore), its size and the time it was taken.
  2. Choose to back up now. The server takes a snapshot, removes the secrets from it, compacts it, records a checksum, restores it into a scratch copy to prove it opens, and only then adds it to the list. The answer says checked: true.
  3. Nightly backups run by themselves. The server checks every 30 minutes and takes one whenever none was made in the last 24 hours.

What is kept #

  • 14 nightly backups and 5 on-demand backups. On-demand backups never push out nightly ones.
  • Before-update and before-restore backups stay until you remove them.

Secrets stay out of backups #

A backup holds no password hash, sign-in token, device key, authenticator secret, webhook signing secret, saved idempotent answer or sign-in attempt. Public link tokens are cleared, and tow call tokens get fresh random values. A stolen backup holds nothing that signs anyone in.

Backup files for another computer #

The folders above stay inside the data folder, so they go down with the computer. For a copy that survives it, Pop Dispatch also makes one encrypted file ending in .psdbackup into a folder you choose (a USB drive or a network share), every night and on request. Restoring one on a new computer needs your recovery key: dispatch-server restore <file>. See "Backup files, schedule and the monthly test" and the playbook "My computer died".

Restore a backup #

  1. Stop the server. Restoring replaces the live database file, so nothing should be using it.
  2. Choose the backup folder. Each backup is a folder under backups in the data folder, named by its time, holding db and manifest.json.
  3. Run dispatch-server restore --from <backup folder> --data-dir <data folder>.
  4. The command checks the backup against its checksums, saves your current data as a before-restore backup named with the time and _prerestore, puts the backup in place and runs the launch check on the result.
  5. Read the message. It lists each owner in the restored data with the exact reset-password command to run for them.
  6. Start the server. The crash count clears, so a server in safe mode starts normally.

After a restore (the reset-password step) #

Passwords, authenticator secrets and webhook secrets stay out of backups, so the owner has three things to redo:

  1. Reset passwords. Run dispatch-server reset-password --tenant <account> --user <email> for each person, starting with the owners. The command prints a one-time password once, clears that person's lockout and ends their earlier sign-ins. At the next sign-in the person must choose their own password. See "Signing in, tokens and lockout".
  2. Set up the authenticator app again for every owner and manager. See "Two-step sign-in for owners and managers".
  3. Make a new signing secret for each webhook endpoint with its rotate-secret call. Until then, queued deliveries wait with the message "The signing secret is missing. Make a new secret for this endpoint."

Also make new integration keys, because token hashes stay out of backups too.

Technical details
  • Layout: backups/<stamp>/db and manifest.json in the data folder. The stamp is UTC time as YYYYMMDDTHHMMSS. The manifest lists the format, kind, applied migrations, and the SHA-256 and size of each file.
  • A backup is written in a staging folder and renamed into place only when whole, so a crash leaves nothing that looks complete.
  • Restore checks the snapshot's checksums first, takes a before-restore backup of the current state (a raw copy when the current file refuses to open), copies the snapshot over the database and removes leftover journal files. A backup folder from outside the data folder is copied into backups first, and a different backup with the same name there stops the restore.
  • GET /backup lists backups and POST /backup takes one. Both are for the owner and both stay open while the licence is read-only.
  • The scrub runs on the snapshot file, never on the live database.

If something goes wrong #

  • The answer to a new backup is server_error: the snapshot failed its restore check and was removed. Check free disk space, then try again.
  • The list is empty: no backup has completed. Take one now.
  • "That backup failed its check": the backup is damaged and the restore stopped. Choose an older one.
  • "has no db and manifest.json": the folder lacks the backup files. Choose the folder named by time inside backups.
  • "The restored data failed its check": choose an older backup. The data you had before is saved as the before-restore backup.
  • People are locked out after a restore: see the steps above, and the playbook "Server down or restoring a backup".