Operate, back up, and restore a LAN Backbone

Last updated: 2026-10-27

Backbone administration is deliberate: syncs, update checks, trust enforcement, migrations, and restores are operator actions. Keep the database, encryption key, and required configuration recoverable before changing the installation.

Sync and status

Creating a provider does not finish its initial import. An approved owner client can queue a full sync on the appliance.

When a sync request is accepted, the job enters the bounded sync queue; acceptance does not mean the catalog is current or complete. Repeated refresh requests do not make a slow provider respond faster.

Inspect the provider sync state, last sync timestamp, error status, and bounded sync summary from a paired client rather than treating an empty catalog as a successful empty provider. Guide status is separate from catalog and playback status.

Check for updates explicitly

If WYREDECK_WAN_URL is configured for the deployment, run:

docker exec wyredeck-backbone wyredeck-backbone update check

This makes one explicit, unauthenticated request for the update manifest at the configured services origin. It reports current and available versions, the running edition's image digest, and any persisted version-floor information. It does not schedule checks, download an update, replace the container, or apply migrations. Without the services-origin setting, the command reports that it cannot check.

Treat the reported image digest and your reviewed distribution provenance as the upgrade reference. An update check is not a release-publication claim.

Back up before every upgrade

Stop writes that you control, then create a consistent backup bundle. The SQLite snapshot can be created while the service runs, but stopping avoidable activity makes the maintenance window clearer. Choose a new bundle name every time:

docker exec wyredeck-backbone \
  wyredeck-backbone backup create \
  --destination /app/data/backups/NEW_BACKUP_NAME

The command checks database integrity and records the migration revision and content hashes. A keyfile-based bundle contains both wyredeck.db and the matching keyfile. Runtime WYREDECK_* configuration is not included and must be saved separately. If the key comes from WYREDECK_ENCRYPTION_KEY, preserve that exact value through your secret-management process instead.

Copy the completed bundle to separate, protected storage before upgrading. The bundle contains the database and encryption material: restrict access as you would for credentials, and never send it to support. Its checksums detect damage; they do not authenticate an untrusted source.

For an existing installation, the safe upgrade order is:

1. Preserve the consistent bundle, original key material, and configuration.
2. Stop the appliance and deploy the reviewed replacement image without deleting the data volume.
3. Run alembic upgrade head with the new image and the same volume and settings.
4. Start only after migration succeeds, then check health and provider access.

A restart alone never performs migration. Do not downgrade a database or erase a volume to make an upgrade appear to succeed.

Restore the database and key as a pair

Restore into a clean data directory. The command refuses to overwrite an existing restore target and never runs migrations. Stop the appliance first.

If the bundle is in the old wyredeck-data volume, this example restores it to a new wyredeck-data-restored volume while mounting the old volume read-only. When the bundle used an environment key, supply that original value through your secret-management process for restore, migration, and startup:

docker run --rm \
  -v wyredeck-data:/source:ro \
  -v wyredeck-data-restored:/app/data \
  wyredeck-backbone-standard \
  wyredeck-backbone backup restore \
  --source /source/backups/NEW_BACKUP_NAME

Then explicitly migrate the restored database with the deployment image:

docker run --rm \
  -v wyredeck-data-restored:/app/data \
  wyredeck-backbone-standard alembic upgrade head

Start with the restored volume and the original configuration only after restore and migration succeed. If validation fails, preserve the bundle and the restored files for diagnosis; choose another clean destination for a corrected attempt rather than blindly overwriting the first one.

Never delete a keyfile or generate a fresh key to bypass a wrong-key error. The original database and key are a recovery pair. A new key cannot decrypt provider credentials, protected source URLs, or an enrolled appliance's WAN device credential.

Reset catalog-removal cursors after restore

Restoring or replacing a database breaks the continuous history assumed by saved catalog-removal cursors. After every restore, each client must discard those cursors, rebuild its active catalog from a fresh snapshot, and only then resume incremental removal polling from the restored history.

This reset is required even though appliance identity and paired devices are restored. Client controls and adoption vary, so do not assume an installed client has already performed the reset. Avoid deleting the appliance database or a provider as a shortcut.

For installation and migration commands, see Install and connect. For protecting the recovery pair, read Security and privacy.