Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Backup files, schedule and the monthly test

Choose where Pop Dispatch saves its single-file backups, see when the last good one was made, and read the monthly test restore result.

For
OwnerAdministrator
Hosting
Office serverYour own hosting
Devices
Server
Business
All businesses

Checked against Pop Dispatch 0.1.0

A backup file is one encrypted file with a name that ends in .psdbackup. It holds your database, every photo and signature, and your licence state. You can copy it to a USB drive or a network drive, and it brings the whole business back on any computer when you type your recovery key. You will be able to choose the folder, read the status and check a file.

Before you start #

  • Only the owner uses backups.
  • Write down your recovery key and keep it away from the server computer. A backup file opens with the recovery key that was current on the day the file was made. See "The vault and your recovery key".
  • The server needs a recovery key before it makes a file. Without one, the status shows the reason and no file is made.

Choose where the files go #

  1. Pick a folder on another drive, such as a USB drive or a network share. The default folder is archives inside the data folder, and a disk failure takes that folder along with the data.
  2. Send PATCH /backup/settings with {"folder": "/Volumes/Backup"} (a full path). The server makes the folder if needed and writes a small test file to prove it can save there.
  3. Set how long files stay with keep_days (30 by default, 1 to 3650). Files older than that are removed after each new backup, and the newest file always stays.
  4. Switch the schedule off with {"enabled": false}. The internal nightly snapshots continue.

What the schedule does #

  1. The server checks every 30 minutes. When no file was made in the last 24 hours, it takes a snapshot, scrubs the secrets, makes the backup file and opens the file again to check it.
  2. When the folder is unavailable, for example the USB drive is unplugged, the status shows the reason and the server tries again every 30 minutes.
  3. Once a month the server restores the newest file into a scratch copy and checks it. The scratch copy is deleted afterwards.
  4. To make a file now, send POST /backup/archives. The answer lists the file name, its size, its checksum and checked: true.

Read the status #

GET /backup/status returns:

  • last_good: when the last file was made, its name, size, row count and number of photo and signature files.
  • alert: true when the last good backup is older than 48 hours, or when no file was ever made. alert_message says what to do. The console can show this as a banner.
  • last_error: the reason the most recent attempt failed, if it did.
  • test_restore: the result of the latest monthly test with its time, the file tested and the row count.
  • folder_is_default: true while files still go to the data folder. Choose another folder.

Check a file yourself #

Run dispatch-server verify-backup <file>. Type your recovery key when asked. The command opens the file, checks every file hash and reports the rows and photos inside. It changes nothing.

Technical details
  • Format: the magic PSDBAK01, a plain header (format, time, random salt and the data key sealed by your recovery key, the same sealed copy as recovery.json), the body in encrypted chunks of up to 1 MiB (AES-256-GCM, a key derived from the data key and the salt, each chunk bound to the header and its position), and a trailer holding the SHA-256 of every byte before it.
  • The body lists manifest.json first, then db, licence-state.json and files/<business>/<file>. The manifest holds the row count of every table and the SHA-256 and size of every file.
  • A file with a changed or missing byte fails the trailer check before any key is asked for, so damage is never reported as a wrong key. A chunk changed with the trailer recomputed fails its own seal check.
  • The database inside is the scrubbed snapshot, so passwords, sign-in tokens, authenticator secrets and webhook secrets are absent. See "Backups and restore".
  • File names read pop-street-dispatch-<UTC time>-<kind>.psdbackup. Retention reads the time in the name, so copying files to another drive keeps it intact. Other files in the folder stay untouched.
  • Settings and status are backup-settings.json and backup-status.json in the data folder, outside the database, so a restore never rewinds them.
  • Optional copy to a bucket that speaks the S3 protocol: set PSD_BACKUP_S3=on, PSD_BACKUP_S3_ENDPOINT (an https:// address), PSD_BACKUP_S3_REGION, PSD_BACKUP_S3_BUCKET, PSD_BACKUP_S3_PREFIX (optional), PSD_BACKUP_S3_ACCESS_KEY_ID and PSD_BACKUP_S3_SECRET_ACCESS_KEY. Each file is sent with a signed PUT over HTTPS. The server removes nothing from the bucket, so set a lifecycle rule there. The status shows the result of the last copy under bucket.
  • The monthly test uses the data key held by the server. It proves the file opens, matches its manifest and passes the data check. To prove your written recovery key, run verify-backup and type it.

If something goes wrong #

  • last_error says the recovery key is missing: the data folder has no recovery.json. Run dispatch-server new-recovery-key, write the key down, and the next backup succeeds.
  • last_error names the backup folder: the drive is unplugged, full or read-only. Reconnect it or choose another folder. The next try follows within 30 minutes.
  • The test restore reports "damaged": the newest file changed after it was written. Make a new file with POST /backup/archives and copy the old one again from its source.
  • The settings call answers "That folder cannot be written to": choose a folder the server's account can write.