Upgrade CM Box

Upgrade a CM Box instance by rolling its four service images to the new release tag together and then completing any migration steps that release requires. There are no database migration scripts to run: all CM Box state lives in Redis, and object migrations happen in the admin UI or automatically in place.

Before you start: you need access to your container platform (Docker Compose, Kubernetes, or a managed container service — see Deployment), the ability to snapshot your Redis data, and a CM Box account with the admin role for any post-upgrade migration steps. Plan a maintenance window: the images are replaced together.

The general procedure

1. Read the release notes for the target version. Each release ships a RELEASE-NOTES-<version>.md change record listing new features, fixes, and — most importantly — an Upgrade Notes section with any actions the release requires of you.
2. Back up Redis. All configuration, content, and security objects live in Redis, so a snapshot is your rollback safety net.
3. Roll all four service images — cm-box-app, cm-box-graphql, cm-box-process, and cm-box-web — to the new version tag and redeploy them together. Do not mix tags across services.
4. Complete the release’s migration steps (if any) from its migration guide or the Upgrade Notes.
5. Verify: sign in, browse content, and exercise the areas the release notes call out as changed.

To roll back, redeploy the previous image tag across all four services. Restore the Redis snapshot only if the release notes say the upgrade changed stored data in a way that is not forward-compatible.

Worked example: upgrading to 2.0

The 2.0 release is the reference example of a migration with admin action required. You can upgrade to 2.0.0 directly from 1.6.x or from any 2.0.0 beta — no intermediate hop, and no Redis schema migration.

Area	Action
License	Action required — 2.0 enforces a valid license at startup
Granular security	Action required — review non-admin roles under the new permission model
WorkOS directory sync	Recommended — re-run a sync after upgrading
Service-account secrets	None — upgraded to hashed storage automatically on next authentication
Conversion settings	None — defaults to all renditions enabled, matching pre-2.0 behavior
Workflow engine	Optional — configure only if you adopt an external engine
V2 user interface	None — ships alongside the V1 interface

Step 1: Confirm the license

2.0 validates the instance license at startup; if it is missing or expired, every page redirects to the License page. Load or replace the license by visiting /license on your instance and submitting the license code — on success you are returned to the content workspace. Licenses are bound to a hostname, so a license issued for one host will not validate on another (remember this when promoting a staging configuration to production). See Instance setup and licensing.

Step 2: Review roles under granular security

2.0 replaces coarse role checks with a granular permission model: permissions are dotted keys checked at global, repository, or site scope, and roles compose them from bundles (named permission sets), scoped individual grants, and per-key overrides. See Security for how to administer the model and the permissions reference for the full key catalog.

What this means for the upgrade:

1. The built-in admin role still bypasses all checks and cannot be deleted, so you cannot lock yourself out.
2. Every other role must now hold the permissions its users need — the new checks fail closed, so an under-provisioned role loses access it previously had.
3. In the admin area, open Security > Roles and assign each non-admin role the bundles that match its job (for example bundle.viewer, bundle.content_editor, bundle.repo_admin). Scope grants to specific repositories or sites where a bundle’s global reach is too broad, and use grant/revoke overrides for single-key exceptions.
4. Sign in with a real non-admin account and verify its access before declaring the upgrade done.

Step 3: Re-run the WorkOS directory sync

Directory sync in 2.0 identifies users by email address instead of the deprecated WorkOS username attribute, and groups by name; end users sign in with their email. After upgrading, trigger a directory sync from the admin security area so existing local users reconcile against email-based identity. Running the sync requires the admin.security.sync permission. See Security for the sync workflow.

What needs no action

• Service-account secrets are now stored hashed. Existing secrets upgrade in place the next time each account authenticates successfully — you do not need to rotate or re-issue them. Newly created or regenerated secrets are shown once, at creation time only.
• Media conversion settings are new in 2.0; a repository with no conversion configuration generates all renditions, which is the pre-2.0 behavior. Trim unneeded renditions per repository later if you want to reduce queue load — see Queues.
• Workflow engine integration is opt-in. Nothing changes until you configure a workflow connection — see Webhooks and workflow.

Verify

• The instance starts and serves the sign-in page without redirecting to /license.
• A non-admin test account can perform its normal work in each repository it should reach — and cannot act where it should not.
• Users provisioned through WorkOS can sign in with their email after the directory sync.
• Media uploads convert and webhooks deliver — check the queue dashboard (Queues) for failed jobs after the first day of use.

Troubleshooting

• Every page redirects to the License page — the license is missing, expired, or issued for a different hostname. Submit a current license for this host at /license.
• A non-admin user lost access after the upgrade — their role has no grant covering the action; the 2.0 checks fail closed. Add the appropriate bundle or scoped permission to the role under Security > Roles.