Your Kitchen Library

Documentation / Backup and Restore

Backup and Restore

Updated: 2026-09-08

Your Kitchen Library includes a portable disaster-recovery path for rebuilding a clean installation from release code, a verified database backup, runtime media, and a separately protected .env. This is the supported product recovery path for v1.0.

Portable v1 disaster recovery

Product tools:

tools/recipe-site-backup.sh
tools/recipe-site-restore.sh

The backup tool creates:

  • a MariaDB SQL dump;
  • the complete www/assets/images/ runtime-media tree;
  • SHA-256 sidecars for both artifacts;
  • a non-secret manifest identifying the release and backup filenames.

The real .env is deliberately excluded. Keep it separately in secure private storage.

Create a portable backup

cd /path/to/recipe-site
bash tools/recipe-site-backup.sh

Optional destination:

bash tools/recipe-site-backup.sh --output-dir /secure/backup/location

The output includes names similar to:

recipe-site-dr_YYYY-MM-DD_HH-MM-SS.sql
recipe-site-dr_YYYY-MM-DD_HH-MM-SS.sql.sha256
recipe-site-dr_YYYY-MM-DD_HH-MM-SS-images.tar.gz
recipe-site-dr_YYYY-MM-DD_HH-MM-SS-images.tar.gz.sha256
recipe-site-dr_YYYY-MM-DD_HH-MM-SS.manifest

Restore to a clean installation

Recovery requires:

  1. matching release code;
  2. a configured .env restored from secure private storage;
  3. Docker running;
  4. the SQL backup plus its checksum sidecar;
  5. the runtime-media archive plus its checksum sidecar.

The normal documented recovery path may first run the product installer. The restore tool therefore accepts only:

  • a truly empty target database; or
  • the pristine v1 installer baseline.

The pristine-baseline comparison ignores only the installation-time metadata timestamps generated in schema_migrations.applied_at and site_settings.updated_at. Schema, keys, row sets, settings, migration names/notes, category/reference data, and every other substantive value must still match. Any modified or populated installation is refused.

Dry run:

bash tools/recipe-site-restore.sh \
  --database /secure/backup/recipe-site-dr_....sql \
  --images /secure/backup/recipe-site-dr_....-images.tar.gz \
  --dry-run

Actual restore:

bash tools/recipe-site-restore.sh \
  --database /secure/backup/recipe-site-dr_....sql \
  --images /secure/backup/recipe-site-dr_....-images.tar.gz

For non-interactive emergency automation, add --yes only when the target has already been verified as the intended clean recovery installation.

The restore tool:

  • verifies both checksum sidecars;
  • rejects unsafe or unexpected archive paths;
  • refuses an arbitrary nonempty/modified database;
  • replaces the pristine installer database before importing the recovered SQL;
  • restores the full runtime image tree;
  • reapplies runtime-media permissions when the helper is available;
  • rebuilds/starts the Compose services;
  • runs product health checks;
  • records the recovered release state.

Clean-machine acceptance record

Portable v1 disaster recovery passed clean-machine acceptance on 2026-09-08 using an ephemeral GitHub-hosted Ubuntu runner.

Final acceptance run:

run: 34265176659
result: success

The test exercised the real install-first recovery path and proved:

  • clean source installation;
  • representative database and media changes;
  • portable backup creation;
  • destruction of the source installation;
  • reconstruction from release code plus protected .env;
  • fresh installation of the pristine 33-table v1 baseline;
  • refusal after deliberately modifying that pristine baseline;
  • recreation of the pristine baseline;
  • restore dry-run validation;
  • successful restore into the pristine installer baseline;
  • database fidelity;
  • runtime-media hash fidelity;
  • refusal of a second restore into the now-populated recovered installation;
  • final product health pass.

The temporary acceptance workflow was closed without merging. Product tooling was merged in PR #340.

Important portable-recovery warnings

  • .env contains deployment secrets and must be backed up separately.
  • Do not keep recovery archives under the public web root.
  • Do not bypass checksum failures.
  • Do not weaken the clean-target guard to make recovery more convenient.
  • A normal existing installation must use the release-to-release upgrader, not the clean-target DR restore tool.
  • Use matching database/media backups whenever possible.

Operational rule

A recovery process is considered release-ready only after both backup creation and an actual clean-target restore have been verified. That requirement is now satisfied for the portable Linux v1 path. Real Windows 10/11 + Docker Desktop acceptance remains a separate outstanding platform verification item.

All documentationAsk a question