ZeroPress Studio Guide

Get Started

Quick Start

Audience: the person deploying and initially administering Studio

This guide covers deployment and the first administrator sign-in. Deploy to Cloudflare creates or connects the resources declared in Studio’s wrangler.jsonc before deploying the Worker. A provisioning failure stops deployment, including for resources whose product features are not in use.

1. Check the deployment prerequisites

  • Use Node.js 22.22.0 or newer when building Studio.
  • Use dedicated Studio D1 (DB) and KV (KV) resources, plus the Edge D1 (EDGE_DB) and KV (EDGE_KV) declared in wrangler.jsonc. For an existing Edge installation, select its matching D1 and KV resources.
  • Keep the STUDIO_AUTH_SECRET Cloudflare Secret stable for the lifetime of the installation. It protects sealed setup data and encrypted MFA material.
  • Create a separate, temporary STUDIO_INSTALL_TOKEN Cloudflare Secret for initial installation.
  • Set the plaintext Worker Variable STUDIO_SITE_MODE to initial.

STUDIO_AUTH_SECRET and STUDIO_INSTALL_TOKEN use the same strict format: 32–256 printable ASCII characters from ! through ~, with no spaces or control characters. Generate independent values; do not reuse either value as a password or operations token.

In initial mode with an uninstalled database, Studio shows one checklist for the active site mode and both required secrets. For each missing or invalid secret, its explicit generate action creates an independent browser-only 256-bit candidate that can be copied into Cloudflare. The equivalent local command is:

openssl rand -hex 32

Read Worker Secrets for the Cloudflare dashboard, Wrangler, and local .dev.vars procedures, and for the distinct lifecycle of all three Studio secrets.

2. Deploy the initial configuration

Deploy the Worker with:

  • plaintext Worker Variable STUDIO_SITE_MODE=initial
  • a valid STUDIO_INSTALL_TOKEN Cloudflare Secret
  • a valid STUDIO_AUTH_SECRET Cloudflare Secret
  • an otherwise uninstalled Studio D1 application catalog

Opening Studio now shows the installation flow. A normal sign-in screen is not available until installation is complete and the operator later changes the site mode.

3. Create the first administrator

The installer asks for the temporary install token and the first administrator’s identity and password. Studio checks the 15–256-character password against the administrator identity, Studio hostname, and its bundled compromised-password list. The product name ZeroPress is not treated as account context.

In a deployed Worker, Studio also checks HIBP Pwned Passwords using the k-anonymity range API. The Worker hashes the password locally and sends only the first five SHA-1 characters with response padding enabled; it never sends the password or full digest. Local development, test, and preview runtimes use the bundled list only. If HIBP is temporarily unavailable, Studio reports that only the bundled list was checked and permits the local policy result.

MFA is mandatory and cannot be disabled:

  1. Register the displayed TOTP secret in an authenticator.
  2. Confirm a current TOTP code.
  3. Submit the installation.

Before writing Studio’s database, the installer checks EDGE_DB:

Edge database state Installation result
Empty application catalog, with EDGE_KV available Initialize Edge and enable Studio’s Edge integration
Non-empty application catalog Preserve it and install Studio with Edge integration disabled
Missing or unreadable Edge DB, missing KV for an empty DB, or failed Edge initialization Stop installation

Studio then commits the administrator, password hash, TOTP factor, system roles, and schema lifecycle state in one atomic D1 batch. It does not create a password-only administrator.

The confirmation code’s 30-second counter step is consumed when installation succeeds. If the authenticator still displays that code at the later sign-in screen, wait for the next code instead of submitting the enrollment code again. Read TOTP Verification for the adjacent-step window and replay-protection rules.

4. Activate the installed Studio

Successful installation does not change the Worker configuration. Before normal sign-in:

  1. Delete the STUDIO_INSTALL_TOKEN binding completely. Leaving it defined, even as an empty value, is a fail-closed configuration error after install.
  2. Change STUDIO_SITE_MODE from initial to operational.
  3. Deploy the changed Worker configuration.
  4. Sign in with the administrator password and a current TOTP code.

Do not rotate STUDIO_AUTH_SECRET as part of activation. Losing or changing it can make existing TOTP and other protected credentials unusable.

5. Configure the first site

A practical first pass is:

  1. Set the site title, canonical URL, locale, and timezone in General.
  2. Review output, URLs, homepage, media delivery, and branding settings.
  3. Create or import Authors, Posts, Pages, Media, Menus, and Widgets.
  4. Review Edge Services and configure the public runtime features you intend to use.
  5. Open Publish, explicitly generate Preview Data, inspect it, and download the JSON for the separate ZeroPress Build workflow.

Studio emits only published Posts and Pages. Draft and Trash content remains in Studio. ZeroPress intentionally does not implement scheduled publishing.

Next steps

  • Follow WordPress Migration to copy existing uploads to R2, import a WXR export, and configure the public media address.
  • Review the Worker Secrets lifecycle and recovery boundary.
  • Review the supported MFA Recovery paths before the only Administrator loses access.
  • Learn when to use each Site Mode.
  • Configure the protected Maintenance & Recovery surface before relying on database backup, restore, upgrade, or recovery workflows.