Upgrades and worker updates

Upgrade the control plane

1. Back up MongoDB and your .env, including ENCRYPTION_KEY.
2. Pull the new version and rebuild: docker compose up -d --build, or repeat the Node.js build steps.
3. Indexes and data migrations run automatically at startup, under a lock.

Workers keep running during the upgrade: they buffer events and retry state changes until the control plane is back. Read the release notes for breaking changes and migration notes before upgrading.

Rotate ENCRYPTION_KEY

1. Generate a new key: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
2. Set ENCRYPTION_KEY to the new key and ENCRYPTION_KEYS_PREVIOUS to the old one; restart. The control plane reads secrets with the old key and re-encrypts them in the background.
3. Confirm: docker compose exec control-plane node apps/api/dist/main.js reencrypt-secrets. Exit code 0 means every secret uses the new key; exit code 2 lists secrets no configured key can decrypt.
4. Remove ENCRYPTION_KEYS_PREVIOUS and restart.

Publish worker releases

The control plane hosts updates for its workers. Releases are signed offline, so a compromised server cannot push code to workers.

1. Once, on a machine you trust: node scripts/sign-release.mjs keygen release-2026. Keep the private key offline; give release-2026.public.pem to your workers (worker UI → Updates → Trusted release keys).
2. Build the package: node scripts/package-worker.mjs --tarball.
3. Dashboard → Server → Worker releases: choose channel and version, upload the package. The page shows the exact signing command.
4. Sign on the trusted machine (node scripts/sign-release.mjs sign … > manifest.json) and upload manifest.json. The server checks that it describes the uploaded package.

Workers with automatic updates install it within six hours; others show it under Updates. See Worker updates for switching and rollback.