ZeroPress Studio Guide

Operations

Maintenance & Recovery

Audience: trusted Studio operators

Maintenance & Recovery is a production operations surface, but it ships disabled. It is intentionally separate from normal administrator authorization because it can export private database contents, recover accounts, delete data, or change database lifecycle state.

Enable the operations boundary

The Worker requires all three settings:

Setting Type Requirement
STUDIO_OPERATIONS_ENABLED Plain variable Exact value true
STUDIO_OPERATIONS_ALLOWED_IPS Plain variable Comma-separated exact IPv4 or IPv6 addresses; no CIDR ranges
STUDIO_OPERATIONS_TOKEN Worker secret 32–256 printable ASCII characters from ! through ~, without spaces or control characters

Generate the operations token independently from the install token and auth secret. If the feature is disabled or the caller’s IP is not explicitly allowed, /system/operations behaves as not found. Secret values are never returned by the status API.

The page performs a tokenless availability check before rendering its sensitive controls. Passing that check does not authorize an operation. The token and, where required, an active administrator’s credentials are verified by the Worker for each protected workflow.

Before any database operation

  1. Identify whether the Studio DB or Edge DB is the target. Their backups and lifecycle state are independent.
  2. Select the required site mode and deploy it.
  3. Stop public writes that are outside Studio’s control. In particular, maintenance mode does not stop the separate Edge Worker.
  4. Create and retain the required reviewed SQL backup when the source database is readable.
  5. Remember that D1 SQL backups do not contain R2 objects. Back up managed media separately.
  6. Keep the operations token, exported SQL, account data, IP addresses, and MFA material confidential.

Studio does not automatically change the site mode, Edge feature gates, or Edge integration mode when work completes.

Studio database backup, restore, and upgrade

Studio exports deterministic logical SQL for the selected database. A data-bearing artifact contains private application and authentication data; its checksum verifies integrity but does not encrypt it.

  • A readable Studio database can be exported in maintenance mode, including when its schema requires an upgrade.
  • Maintenance-mode export and normal restore paths re-confirm an active administrator.
  • Recovery mode uses the exact-IP and operations-token boundary when account or role data cannot be trusted.
  • Restore is journaled and bounded. If it is interrupted, resume the same restore from the recorded progress rather than starting a competing one.
  • A forward-only upgrade applies reviewed consecutive schema artifacts. Each committed version is the retry boundary after an interrupted response.

After an upgrade reports completion, return to operational and smoke-test sign-in, MFA, Dashboard, important settings, content reads, and Preview Data. Return to maintenance and retain the backup if any check fails.

Edge database lifecycle

Edge owns its canonical schema contract; Studio contains a reviewed, checksum-verified copy so Maintenance & Recovery can operate without reading a sibling source repository at runtime.

The lifecycle action depends on the inspected state:

  • Install accepts an otherwise empty Edge application catalog.
  • Adopt accepts only an exact unversioned Edge v1 catalog and canonical initial seeds, then adds lifecycle state without changing business data.
  • Upgrade applies the next reviewed, consecutive forward-only artifact.
  • Partial, unexpected, malformed, in-progress, or newer-than-code state is not silently repaired.

The exact default-value comparison is specific to legacy adoption. After a database is lifecycle-managed, legitimate Edge settings may differ from their installation defaults while required row identities and schema constraints remain valid.

EDGE_KV is not required for database lifecycle work. It is checked when the operator later enables Studio’s Edge integration.

Edge target reconciliation

Reconciliation repairs the handoff between Studio Posts/Pages and Edge comment targets without automatically deleting Edge-only data. It proceeds in bounded, repeatable phases:

  1. drain pending target-projection events;
  2. upsert Studio Posts in public-ID order;
  3. upsert Studio Pages in public-ID order;
  4. scan Edge targets and snapshot orphans;
  5. review and optionally purge selected orphans;
  6. verify an empty outbox and exact target parity before finalizing.

An orphan purge deletes at most 100 selected targets per request. Immediately before deletion, Studio rechecks that the target is still absent, that its identity and mutable snapshot have not changed, and that the expected comment count still matches. A successful target deletion cascades all of its comments. Changed or revived targets are skipped.

Steps are idempotent and safe to retry after a lost response. Cancelling removes only the Studio reconciliation journal and orphan snapshot; already completed upserts remain. Reconciliation never enables Edge integration automatically.

Use this Edge runbook:

stop public Edge feature gates
→ switch Studio to maintenance
→ export and retain an Edge SQL backup
→ install, adopt, or upgrade Edge DB as required
→ run reconciliation and review every orphan
→ return Studio to operational
→ enable Edge Services after health checks pass
→ reactivate public Edge feature gates

Account recovery

Recovery mode can replace a selected administrator’s password and mandatory MFA material without creating a normal Studio session. Use it when the account credentials or STUDIO_AUTH_SECRET-protected TOTP data cannot be used.

After recovery, Studio still does not change STUDIO_SITE_MODE. Switch to operational, complete the required password and MFA flow, and verify access. If the schema also requires an upgrade, recover the account first, then switch to maintenance and follow the backup-and-upgrade runbook.

Destructive operations

  • Clear site content removes site content while preserving system settings and the intended non-content configuration. It may be available in operational or maintenance mode.
  • Reset Studio removes site configuration and content while preserving the current administrator so the site can be configured again. It is maintenance-only.
  • Uninstall Studio removes the Studio application schema and accounts. It is maintenance-only and does not delete R2 objects.

Each destructive operation uses an exact confirmation phrase, administrator reconfirmation where applicable, and a final execution confirmation. Do not infer success from a modal closing; wait for the completed result and preserve its report.

To reinstall after uninstall, set STUDIO_SITE_MODE=initial, create a new temporary install token, deploy the configuration, and use the normal installer.

Close the maintenance window

  1. Confirm the operation’s final status and retain its report and backup.
  2. Change STUDIO_SITE_MODE to operational and deploy.
  3. Verify password + MFA sign-in and the application smoke tests relevant to the operation.
  4. Re-enable public Edge gates only after Edge lifecycle and reconciliation are complete.
  5. Disable the operations surface when it is not actively needed, or restrict its exact-IP allowlist and token according to the site’s operational policy.