Skip to content

Administrator guide

Upgrade safely

Select the latest signed stable release or an exact image, apply it transactionally, and prove the result.

opencircle upgrade is the day-two replacement path for Compose profiles. opencircle deploy is not — deploy has no automatic backup and no rollback. For Railway, use the separate protected upgrade and resume path instead.

Plan without mutation

Terminal

opencircle profile list
opencircle status --profile circle-server
opencircle release plan --profile circle-server

release plan previews the default server-only artifact and a compatibility check — it is read-only. There is no separate apply command; upgrade owns the mutation.

Select the release

Terminal

opencircle upgrade \
  --profile circle-server \
  --backup-dir /path/to/operator-controlled-backups

Bare upgrade verifies the signed stable channel and selects its exact immutable digest before the transaction begins. To move to a specific reviewed release instead, pass its canonical reference:

Terminal

opencircle upgrade \
  --profile circle-server \
  --image ghcr.io/opencircle/opencircle-runtime@sha256:<image-digest> \
  --backup-dir /path/to/operator-controlled-backups

The default replaces only the OpenCircle Server component; add --full only when a release explicitly requires a full-stack replacement.

Transaction boundary

The guarded path drains work, stops the Server, creates and verifies a full recovery bundle, applies the selected artifact, runs an acceptance check, and clears maintenance. On failure it restores the bundle and prior image and proves health before finishing.

--no-rollback deliberately leaves the failed target and bundle for manual investigation. It is not a faster ordinary upgrade — record the bundle path before using it.

Verify and recover

After success, compare the deployment identity with the immutable artifact and prove owner sign-in plus the feature you upgraded for. If automatic rollback fails, treat the target as critical: preserve the bundle, prior-image identity, and logs, then follow Back up and restore.