Site Modes

Audience: Studio operators

STUDIO_SITE_MODE is a Worker deployment setting, not a Studio database value or site-content preference. Studio accepts exactly four values. A missing or unknown value fails closed.

Mode	Intended use	Normal sign-in and product APIs	Maintenance & Recovery
initial	Install a new Studio database	Blocked	Installer only
operational	Normal authoring and administration	Available when the schema is current	Limited operational actions may be available
maintenance	Planned backup, schema lifecycle, reconciliation, reset, or uninstall	Blocked before product D1 access	Maintenance workflows
recovery	Out-of-band account or database recovery	Blocked before product D1 access	Recovery workflows

initial

Use initial only with an uninstalled Studio database, a valid temporary STUDIO_INSTALL_TOKEN, and the permanent STUDIO_AUTH_SECRET. It exposes the first-administrator installation flow.

Installation never changes this setting. After a successful install, remove the install-token binding, change the mode to operational, and deploy the new configuration. Keeping an install token after installation is treated as an invalid lifecycle configuration rather than a reusable installer.

operational

Use operational for normal sign-in, content work, settings, imports, and Preview Data generation. It does not override database compatibility:

• an uninstalled database remains blocked;
• an older supported schema reports that an upgrade is required;
• an in-progress, malformed, or newer-than-code schema remains unavailable.

When an upgrade is required, first switch to maintenance. A button that merely opens Maintenance & Recovery cannot make upgrade controls available while the Worker remains operational.

The operations surface may expose Clear site content in operational mode, but reset, uninstall, schema upgrade, Edge lifecycle, and reconciliation remain maintenance-only.

maintenance

Use maintenance for planned work that requires the normal Studio application to stop. The global API gate rejects ordinary product routes before querying the product database. Existing browser sessions do not bypass this boundary.

Maintenance is the required mode for:

• Studio DB forward-only upgrades;
• Edge DB install, explicit legacy adoption, and forward-only upgrades;
• Edge target reconciliation and orphan review;
• Reset Studio and Uninstall Studio;
• maintenance-mode database backup and supported restore workflows.

The separately deployed Edge Worker is not stopped by this mode. Disable its COMMENTS_ENABLED, FORMS_ENABLED, and NEWSLETTER_ENABLED hard gates before Edge database maintenance.

recovery

Use recovery when normal account authentication or Studio database state is the thing being repaired. Normal login and product APIs remain blocked. Access uses the separately configured operations token and exact-IP boundary rather than creating a regular Studio session.

Recovery can support administrator password/MFA recovery and appropriate SQL restore paths. It does not expose Reset Studio or Uninstall Studio, and Edge DB lifecycle or target reconciliation still requires maintenance.

Typical transitions

new deployment
  initial → install → remove install token → operational

planned schema work
  operational → maintenance → backup → upgrade → operational smoke test

lost administrator access
  operational → recovery → recover account → operational

lost access plus outdated schema
  recovery → recover account → maintenance → backup and upgrade → operational

No Studio button performs these mode transitions. The operator changes the Worker configuration and deploys it explicitly.