Skip to content

feat: add encrypted self-hosted backup and restore#950

Open
Coke1120 wants to merge 3 commits into
phasehq:mainfrom
Coke1120:codex/issue-949-backup-restore
Open

feat: add encrypted self-hosted backup and restore#950
Coke1120 wants to merge 3 commits into
phasehq:mainfrom
Coke1120:codex/issue-949-backup-restore

Conversation

@Coke1120

@Coke1120 Coke1120 commented Jul 22, 2026

Copy link
Copy Markdown

🔍 Overview

Adds a supported encrypted backup, integrity verification, and restore workflow for the default self-hosted Docker Compose deployment requested in #949.

💡 Proposed Changes

  • add phase-admin backup, verify, and restore commands with focused help
  • include PostgreSQL data, decryption-critical environment values, resolved Compose configuration, source revision/image metadata, and checksums
  • compress and encrypt archives with AES-256-CBC and 200,000 PBKDF2 iterations
  • validate archive paths, member types, format metadata, required environment values, and checksums before extraction or mutation
  • replace the public PostgreSQL schema atomically so post-backup objects cannot survive restore
  • reject incompatible existing database identities and support fresh-host restores with an empty volume
  • stop writers before restore, preserve the prior environment, roll back pre-commit failures, and give explicit recovery steps for post-commit migration/startup failures
  • document scope, version guidance, destructive confirmation, and off-host retention
  • ignore generated archives and pre-restore environment files

Application export/import, Kubernetes backup, scheduling, retention automation, and object-storage upload remain separate follow-ups.

📝 Release Notes

Administrators of the default Docker Compose deployment can create, verify, and restore password-encrypted instance backups with phase-admin.

🧪 Testing

Local checks:

  • shellcheck phase-admin tests/test-phase-admin.sh tests/test-phase-admin-compose.sh
  • bash -n phase-admin tests/test-phase-admin.sh tests/test-phase-admin-compose.sh
  • tests/test-phase-admin.sh
  • git diff --check

The mock integration test covers backup, offline verification, pre-commit restore failure, post-commit migration failure, same-instance restore, and fresh-host restore.

The exact schema-reset and plain-dump restore pipeline also passed against an isolated PostgreSQL 15.18 instance. It restored the backed-up value to before and confirmed a target-only table was removed (before|t).

CI adds a PostgreSQL 15.4/Compose integration test for the same data and target-only-object assertions. GitHub has created the fork workflow runs with action_required; they await maintainer authorization.

🎯 Reviewer Focus

Start with phase-admin's extract_and_verify and restore functions, then tests/test-phase-admin-compose.sh.

✨ How to Test the Changes Locally

  1. Start a Docker Compose Phase deployment.
  2. Run ./phase-admin backup --output phase-backup.tar.enc.
  3. Run ./phase-admin verify phase-backup.tar.enc.
  4. Restore into a disposable deployment with ./phase-admin restore phase-backup.tar.enc.

💚 Did You...

  • Ensure linting passes (ShellCheck and Bash syntax)
  • Update dependencies and lockfiles (not required)
  • Update migrations (not required)
  • Regenerate GraphQL schema and types (not required)
  • Verify the scripts, mocked workflows, and restore transaction locally
  • Manually test browsers/devices (not applicable to this CLI-only change)

Addresses #949.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant