Skip to content

Backups and restore

aseStack separates controller recovery, database archives, and selected-server system snapshots. Choose the narrowest backup source that matches what you need to recover, and test restoration before relying on a schedule.

Keep an independent recovery copy

A backup visible in the same control panel is not enough on its own. Keep a verified copy outside the controller host and protect the backup credential key separately from the provider account it unlocks.

Choose a backup source

Source Contains Restore path
Control plane aseStack data and configuration, controller CA material, users, fallback state, and a PostgreSQL dump when configured and available Guarded control-plane restore
Existing local archive A previously created and verified local aseStack archive Guarded control-plane restore
PostgreSQL A logical PostgreSQL dump packaged with metadata and checksum PostgreSQL-aware readiness and restore tooling
MySQL/MariaDB A logical database dump packaged with metadata and checksum Databases import handoff; not automatic control-plane restore
System snapshot Selected, allowlisted paths from one managed agent Selected-server staged and explicitly approved restore workflow

System snapshots are application-aware archives, not whole-disk images. They exclude raw block devices, Docker overlay internals, pseudo filesystems, and unbounded traversal from /.

Create a local controller backup

The installer creates /var/backups/asestack as the default local archive directory. Create and verify an archive from the controller host:

sudo /opt/asestack/deploy/backup-state.sh create
sudo /opt/asestack/deploy/backup-state.sh verify \
  /var/backups/asestack/asestack-YYYYmmddTHHMMSSZ.tar.gz

Each archive has a .sha256 sidecar. When PostgreSQL is configured, use pg_dump from the same major version as the server or newer.

The archive can contain user records, runtime configuration, controller CA private material, provider settings, and database state. Store it as sensitive data.

Configure a backup account

The Backups workspace supports these destination types:

  • local directory
  • S3-compatible storage, including Cloudflare R2
  • Google Drive
  • Dropbox
  • OneDrive
  • SFTP

  • WebDAV

  • Set a long random ASESTACK_BACKUP_CREDENTIAL_KEY before saving provider secrets.

  • Open Backups, add an account, and choose the provider.
  • Enter only the fields shown for that provider.
  • For OAuth providers, register the callback URI shown by aseStack and use the in-app authorization flow.
  • Test the account before saving it.
  • Run a small upload/download proof with a disposable archive before scheduling production data.

Saved secret fields are encrypted and API responses redact them. If the backup credential key is lost, existing encrypted provider secrets cannot be recovered; rotate the provider credentials and create new profiles.

Schedule backups

Create a schedule only after its source and destination both pass a manual test.

  1. Open Backups and create a schedule.
  2. Select the source, managed server when applicable, destination account, timing, and retention policy.
  3. Save the schedule and use Run now for the first execution.
  4. Inspect run history, archive name, checksum, remote path, and any cleanup report.
  5. Confirm the uploaded archive and sidecar exist at the destination.

Automatic due-schedule execution is opt-in:

ASESTACK_BACKUP_PROVIDER_TRANSFER_ACTIONS=true
ASESTACK_BACKUP_SCHEDULE_RUNNER=true
ASESTACK_BACKUP_SCHEDULE_INTERVAL=1m

Retention deletion is a separate gate. With ASESTACK_BACKUP_RETENTION_DELETE_ACTIONS=false, aseStack reports what would be removed without deleting provider objects. Review several dry runs before enabling deletion.

Restore controller state

Plan a maintenance window. A control-plane restore can replace configuration, users, controller CA state, and PostgreSQL-backed state.

  1. Verify the archive and checksum sidecar.
  2. Make sure the archive is present in the configured local backup directory, downloading it from a provider if necessary.
  3. In Backups, run Restore Readiness for the archive and target.
  4. Resolve every blocking item: required tools, archive readability, database dump compatibility, database URL, restore script, and service impact.
  5. Create one more current backup before applying the older archive.
  6. Enable live restore only for the maintenance window:
ASESTACK_RESTORE_ACTIONS=true
  1. Submit the guarded restore, monitor service logs, and disable the gate afterward.
  2. Verify direct health, public health, login, agent heartbeats, settings, and backup inventory.

For a root-run manual restore:

sudo ASESTACK_RESTORE_CONFIRM=restore \
  /opt/asestack/deploy/backup-state.sh restore \
  /var/backups/asestack/asestack-YYYYmmddTHHMMSSZ.tar.gz

Do not run that command until readiness checks and the maintenance window are accepted.

Restore database archives

  • A PostgreSQL control-plane archive requires a reachable database and pg_restore with sufficient privileges.
  • A MySQL/MariaDB schedule archive contains asestack-backup/mysql.dump; use the Databases import handoff after readiness checks.
  • Do not restore live database data directories from a system snapshot. Use logical database dumps.

Restore a system snapshot

System snapshot restore is deliberately multi-stage and selected-server only:

  1. Verify the completed handoff, controller-local copy, sidecar, and manifest.
  2. Run restore preflight and review the proposed target paths.
  3. Review the dry-run, service impact, health probes, and rollback criteria.
  4. Generate and accept the approval package.
  5. Prepare rollback archives for every overwrite target.
  6. Stage snapshot contents and inspect the staging root.
  7. Apply only with the exact final confirmation token shown by aseStack.
  8. Run the operator-managed service sequence and health checks.
  9. If validation fails, use the separately guarded rollback application and its exact rollback token.

The controller and agent use separate gates for snapshot create, upload, health-check, restore, and rollback actions. Enable only the gates required for the current window, then turn them off.

After any restore

sudo asestack health
sudo asestack status
sudo asestack logs-app

Also verify:

  • public HTTPS and the correct health metadata
  • owner login, MFA, and passkeys on the current hostname
  • fresh managed-agent heartbeats
  • controller CA continuity or re-enrollment needs
  • saved provider profiles and a small transfer proof
  • a new post-restore backup

If the controller is being moved rather than recovered in place, preserve the old controller until the new host has passed these checks.