Skip to main content

This-Computer Upgrade and Rollback

Upgrades move all four products and the database schema forward together; rollback restores the previous release together with the database backup taken before it.

Step 1: Check What Is Installed​

soln status --dir "$HOME/soln-tenant-runtime"
  • Success: prints the installed release version, the container state of the four products, and ready
  • DEPLOYMENT_NOT_INSTALLED: No Soln deployment state exists in this directory. — the directory is not a deployment directory; check the path as described in Deployment Files and Directories

To ask the Control Plane whether a newer release exists:

soln upgrade --check --dir "$HOME/soln-tenant-runtime"
  • Soln <version> is up to date. — nothing to do
  • Update available: <current> -> <next> — continue with step 2
  • Update required: <current> -> <next> — the Control Plane enforced this release; upgrade to keep the Runtime connected

Step 2: Free Disk Space First​

df -h "$HOME"
  • Success: the Avail column is at least 10 GiB. An upgrade keeps the old and the new images side by side for a short time and writes a database backup
  • Less than 10 GiB — free space first; the upgrade fails with DEPLOYMENT_DISK_INSUFFICIENT before it changes anything

Step 3: Upgrade​

soln upgrade --dir "$HOME/soln-tenant-runtime"

Add --yes to skip the confirmation prompt, and --release <version> only when you need one exact release. In order, the CLI:

  1. runs the soln doctor checks and stops on the first failure
  2. verifies that the environment still matches the recorded deployment state (DEPLOYMENT_BINDING_MISMATCH otherwise)
  3. writes the PostgreSQL backup to <deployment>/.soln/backups/postgres-tenant-<timestamp>.sql.gz.enc
  4. records the pending upgrade in .soln/deployment.json, so a crash mid-upgrade can still be recovered
  5. re-verifies the signed release manifest and the Cosign bundle of every image, then pulls them with short-lived pull-only credentials
  6. runs the Database Migrator
  7. restarts Runtime Service, Runtime Web, and the Workflow Worker
  8. waits for /health/ready and then clears the pending operation
  • Success: Soln upgraded to <version>. Backup: <deployment>/.soln/backups/postgres-tenant-<timestamp>.sql.gz.enc
  • DEPLOYMENT_ALREADY_CURRENT — that release is already installed; nothing to do
  • DEPLOYMENT_RECOVERY_REQUIRED — a previous upgrade did not finish; run rollback first (step 5)
  • The upgrade fails before touching the database when a signature check or a doctor check fails; fix the cause and run the same command again

Step 4: Verify the New Version​

soln status --dir "$HOME/soln-tenant-runtime"
  • Success: the release version is the new one and the state is still ready
curl -fsS -o /dev/null -w '%{http_code}\n' https://soln-<tenant-subdomain>.localhost:8443/health/ready
  • Success: 200
  • Anything else: roll back (step 5) instead of editing files by hand

Step 5: Roll Back​

soln rollback --dir "$HOME/soln-tenant-runtime"

Use it when a migration or a health check failed, or when the new release behaves worse than the previous one. The CLI:

  1. confirms the previous release and its database backup are still available (DEPLOYMENT_ROLLBACK_UNAVAILABLE otherwise)
  2. stops the business services
  3. restores the PostgreSQL backup
  4. runs the Database Migrator for the previous release
  5. starts the previous release and waits for /health/ready
  • Success: Soln rolled back to <version>.
  • No previous release and database backup are available. — either nothing was upgraded yet, or a rollback already consumed the backup; check soln status
  • After a rollback the previous release becomes current and no further rollback target is kept, so the next upgrade takes a fresh backup

Rules​

  • Never edit .soln/deployment.json or .soln/docker-compose.release.yml: they record the installed release, the digests, and any pending operation
  • Keep .soln/backups on the same encrypted disk and do not delete a backup that belongs to the running release
  • Rotate the Agent secret only when you intend to reconnect the Runtime; in a this-computer deployment the secret lives only in the deployment .env
  • Do not run soln install again in this directory (DEPLOYMENT_ALREADY_INSTALLED); upgrades and rollbacks are the supported path