Restore

Restoring a backup replaces your current database and media files with the contents of a backup archive. Restore from an uploaded file, from a backup stored on this server, from a remote DO Spaces copy, or over the API.

What gets replaced

A restore replaces:

the database
the media directory
theme files and site templates, when the backup contains them
theme metadata, when included

The action cannot be undone, so the interface warns you before anything changes and asks you to confirm.

Where you restore from

Upload a backup file from the Restore from Backup form on the Backups screen. The file must be a .tar.gz archive no larger than 50 MiB.

Restore a local backup from the list of archives saved on the server, using its Preview or Restore button. Local backup files are recognized by their chinaski_backup_<timestamp>.tar.gz naming pattern.

Restore from DO Spaces: if Spaces is configured under Settings → Integrations, you can restore from a remote backup list. On an air-gapped instance remote restore is disabled.

API restore: an endpoint lets clients with a write API key restore a named local backup, including the same dry-run preview the admin screens use.

Always preview first

Click Preview (dry run) before restoring. A dry run reads the archive and reports, without changing anything:

the backup’s type, creation date, hostname, and CMS version
its schema version compared to your current one; a mismatch is highlighted and guarantees the restore will abort
what the archive includes (media, themes, site templates)
the result of an integrity check on the backed-up database
any validation failures or legacy-backup warnings

Backups made by a recent version include a checksum manifest. If it’s present, restoring verifies every file inside the archive against its recorded SHA-256 checksum; mismatches abort the restore with “backup may be corrupted or tampered with”. Older “legacy” backups restore fine but let you know checksums were not verified.

For uploaded backups the verification runs against the exact staged file you previewed, so what you confirm is what gets applied. If new previews supersede that staged upload, the older confirm is refused.

What’s enforced

These gates run before anything is changed:

Schema version must match exactly. A backup of a different schema version aborts the restore entirely before anything changes.
Archive must contain the database file: anything that isn’t a Chinaski backup is refused.
Files must stay inside the archive. Extraction walks through the list of locations and aborts if any entry tries to escape the extraction directory (symlink or path-traversal tricks).
Checksums must match. When the archive carries a manifest, every listed file is SHA-256 verified.
A 120-second timeout applies to downloads and extraction; a restore that doesn’t finish in time is discarded rather than applied late.

What’s shown on success, and what you need to do

Once a restore starts applying, the database is replaced first, atomically. Then media, themes, and site templates follow:

On a clean restore you see “Backup restored: database, media, and themes have been replaced”. Remote/API restores tell you the same and add: restart the service to reload the database. Restarting after any restore is a sensible practice.
If only the database restored but media couldn’t be swapped in (rare, usually permissions), the message tells you to re-run the restore to retry the media step.
If themes or site-template restoration failed while everything else worked, the flash names what to double-check.
Successful restores are recorded in the audit log with the backup’s origin.