Skip to content
Back to

Backup and restore

Fontana gives you two complementary recovery paths: platform snapshots for host-level upgrade rollback, and application configuration export and import in Flow for migrating or restoring workspace settings. Together they cover release safety, operator change control, and configuration portability without mixing secrets into export files.

Platform snapshots and rollback

Section titled “Platform snapshots and rollback”

Before a workspace upgrade, the host can take an automatic full-stack snapshot: the pinned release metadata plus the workspace data volume. That gives you a reversible change-control point when applying a new Fontana version. Retention uses a grandfather-father-son (GFS) policy in fontana.yaml so deploy churn and longer-horizon recovery points stay separate.

Capability What it does for you
Pre-upgrade snapshot Captured when the bundle release changes and snapshots.on_apply is true
Daily / monthly Optional scheduled dailies (Linux systemd); monthlies are promoted from dailies without a second cluster stop
Manual snapshot fontana snapshot create <tenant> [--kind=…] before risky changes
Rollback Restores the data volume and redeploys the pinned release from the chosen snapshot
Retention GFS tiers: snapshots.retain.{deploy,daily,monthly} under separate kind folders

Rollback is an operator action on the host via the Fontana CLI (fontana rollback). It is the primary path when an upgrade must be undone quickly while keeping workspace data intact.

Configure GFS retention
Section titled “Configure GFS retention”

Declare policy once in fontana.yaml. Integer snapshots.retain is not accepted; use the tiered object.

snapshots:
  on_apply: true # false on local edit-loop hosts
  retain:
    deploy: 5 # newest pre-upgrade / destroy snapshots
    daily: 10 # scheduled or manual dailies
    monthly: 24 # promoted from daily (one per UTC month kept up to this count)
  schedule:
    daily: "03:15" # UTC HH:MM; omit when retain.daily is 0
Kind Folder under snapshots root <tenant>/ How it is created
deploy deploy/ Apply / destroy when on_apply is true; or fontana snapshot create (default)
daily daily/ Systemd timer after apply reconciles schedule.daily; or --kind=daily
monthly monthly/ Automatic promote from the newest daily in the current UTC month

On Linux ghcr hosts the snapshots root is /var/lib/fontana/persistent/fontana-snapshots when that data mount exists; otherwise $FONTANA_HOME/snapshots.

Prune runs per kind. A burst of deploy snapshots only trims deploy/; daily and monthly recovery points stay until their own retain limits apply.

fontana apply also installs or removes Linux systemd units fontana-snapshot-daily@<tenant>.timer to match your YAML. On macOS, or without systemd, timers are skipped and logged; you can still create dailies by hand.

After each snapshot stop/start, the CLI unseals tenant Vault so auth and core services can load secrets. When remoteStore is set, S3 credentials are required before the cluster stops, and daily timers load /root/fontana-operator.env as a required environment file.

Terminal window
fontana snapshot list demo
fontana rollback demo deploy/<stamp>_<version>

See Fontana CLI → Full-stack snapshots for local vs production examples, promote behaviour, and rollback name rules.

Application configuration export and import (Admin)

Section titled “Application configuration export and import (Admin)”

In Flow, Admin → Deployment → Export/Import exports and imports a composite configuration file for your workspace. Use it to clone settings across environments, recover after a configuration mistake, or document approved platform state.

Export includes (non-secret application configuration):

  • Roles, teams, and users (users merge by email on import)
  • Workflows and workflow documents
  • AI agents, skills, skill assignments, and approved model lists
  • MCP and external agent interop connections (connection definitions in the export file)
  • Knowledge Graph sources and documents
  • Non-secret platform configuration keys

Export does not include:

  • BYOK and other Vault secrets - LLM keys, identity SMTP credentials, and other sensitive values stay in Vault; restore them through your secret-management procedures
  • Workflow run datasets - tabular run data and exports live in workspace storage (see Storage and processing); use platform snapshots or your DR policy for volume-level recovery

Import shows a preview with per-section choices: skip duplicates, overwrite, or import as duplicate. You control which sections apply before committing. If a section batch returns errors, import fails closed: later sections do not continue, and you see a failure message so a partial destructive apply does not proceed quietly.

Requires platform:write permission (typically administrators).

When to use which path

Section titled “When to use which path”
Scenario Recommended path
Undo a failed platform upgrade Platform snapshot rollback via Fontana CLI
Migrate workflows and AI config to another workspace Admin Export/Import composite file
Recover secrets and BYOK Vault backup procedures (operator runbook); composite export excludes secrets by design
Recover workflow run history and uploads Platform snapshot rollback or volume-level DR per your host policy
Change control before a host maintenance window Manual platform snapshot + optional Admin export

Upgrades and change control

Section titled “Upgrades and change control”

Production deploys use immutable release tags so every upgrade is reproducible and auditable. The automatic pre-upgrade snapshot is part of that story: you can always roll back to the prior release and data state if validation fails after apply.

For day-to-day reconciliation on the host, see Fontana CLI (fontana apply, snapshot, and rollback commands). There is no per-tenant upgrade verb: shared static SPAs and backends reconcile together via fontana apply.

Section titled “Related documentation”