Skip to content
CM Box Documentation

Set up a new instance

Complete the one-time Instance Setup screen so your CM Box deployment has a hostname, initial administrators, a storage backend, and a valid product license. Until setup is complete, every page on the instance redirects to /instance_setup.

Before you start:

  • The instance is deployed and healthy.
  • You have a license code from Fishbowl Solutions Support. Licenses are bound to a hostname and an expiration date, so request the license for the exact hostname users will access (for example mycontent-app.cmbox.io).
  • You have your storage backend details ready — see Storage backends for what each provider needs.
  • Authentication prerequisites are in place (see Authentication prerequisites below).

Steps

Section titled “Steps”
  1. Browse to your CM Box instance. A fresh instance redirects you to the Complete CM Box Instance Setup form.
  2. In Instance Configuration, fill in:
    • Instance Hostname — the hostname where the instance is accessed (for example mycontent-app.cmbox.io). This must exactly match the hostname in your license, and it is also used to build the sign-in callback URL.
    • Instance Label — a display name shown in the UI (for example Production).
    • Admin Emails — a comma-delimited list of email addresses. Each one is created as a user with the admin role.
  3. In Storage Configuration, choose a Storage Provider — Oracle Cloud Object Storage, Azure Blob Storage, or Oracle WebCenter Content — and complete its fields:
    • Oracle Cloud Object Storage: Compartment ID, Namespace, Configuration Profile Name (typically DEFAULT), and two file uploads — the OCI Connection Config File and the OCI Private Key File for a service user with access to storage buckets.
    • Azure Blob Storage: the Azure Blob Storage Connection String.
    • Oracle WebCenter Content: the URL, Service Username, and Service Password.
  4. In License, paste the License Code provided by Fishbowl Solutions Support.
  5. Click Submit. The page confirms Instance Settings Saved.
  6. Click Continue to go to the content area and sign in.

Verify

Section titled “Verify”
  • After submitting, Instance Settings Saved. appears and Continue takes you to /content.
  • Sign in with one of the admin email addresses you entered; the account has the admin role and can open the Admin area.
  • Revisiting /instance_setup now shows “Instance Setup has already been completed. Edit settings in the Admin Area.”

How licensing works

Section titled “How licensing works”

CM Box validates the license on every page request (API routes under /api/ are exempt, so published content keeps flowing while you fix a license). A license is valid when all three checks pass:

  • the hostname embedded in the license matches the instance hostname you entered during setup,
  • the expiration date has not passed,
  • the license signature verifies.

When validation fails, the UI redirects to the Update License screen at /license, where you paste a new license code. On success the page shows License Updated.; an invalid code shows Invalid License with a Re-Enter License link.

To change settings captured at setup time (including the hostname a license is validated against), you can re-open the setup form pre-filled with current values at /instance_setup?bypassSetupCheck=1.

Authentication prerequisites

Section titled “Authentication prerequisites”

CM Box user sign-in is handled by WorkOS AuthKit. At a high level, your instance needs:

  • WORKOS_ORGANIZATION_ID — the WorkOS organization users sign in through. Sign-ins from any other organization are rejected.
  • WORKOS_DIRECTORY_ID — optional; the WorkOS Directory Sync directory used to synchronize users and groups into CM Box.
  • CMBOX_ENVIRONMENT — set to prod for production deployments so the instance uses the production WorkOS environment (any other value selects the development environment).
  • A callback URL of https://<instance hostname>/callback registered as the redirect URI in WorkOS. CM Box derives this URL from the instance hostname you enter during setup.

These values are supplied as environment variables on the app and graphql services — see the environment variable reference. Fishbowl Solutions provisions the WorkOS organization and directory values with your license.

Troubleshooting

Section titled “Troubleshooting”
  • Stuck on the license screen after setup — the hostname in the license does not match the instance hostname. Open /instance_setup?bypassSetupCheck=1, confirm Instance Hostname exactly matches the hostname your license was issued for, and re-enter the license code.
  • Sign-in fails after setup — confirm WORKOS_ORGANIZATION_ID is set on the app service and that the /callback URL for your instance hostname is registered in WorkOS.
Section titled “Related”