Installation

Use Setup to provision Authrim and generate its deployment configuration. Creating three D1 databases or running individual legacy setup scripts is not a complete installation of the current architecture.

Requirements

• Node.js 22.18+ (22.x) or 24.11+ and pnpm 9, matching the repository’s package configuration.
• Git and a Cloudflare account with permissions for the resources being deployed.
• A domain/DNS configuration appropriate to the selected API and UI URLs, or the supported Workers domain configuration offered by Setup.
• An email provider if users will sign in with email codes. Configure delivery and the sender; do not rely on missing production credentials causing codes to appear in logs.

The required Cloudflare services depend on enabled features. Check account limits and service availability for Workers, D1, KV, Durable Objects, Queues, and R2 rather than assuming every configuration fits the free plan.

Install from source

Check out the release you intend to install. A development branch and a published release can have different migration requirements.

git clone https://github.com/sgrastar/authrim.git
cd authrim
pnpm install
pnpm exec wrangler login
pnpm run setup init --env prod --lang en

init offers the guided setup flow. To use the terminal interface directly:

pnpm run setup init --env prod --cli --lang en

Use pnpm run setup, not pnpm setup: the latter invokes pnpm’s own setup command. Do not insert an extra -- before init or other subcommands.

The published npx @authrim/setup launcher is another entry point. It resolves source for the setup process; it is not a self-contained replacement for all deployment source files. Use one source directory and keep its environment configuration for subsequent operations.

What Setup manages

Setup collects the environment, domains, feature choices, and administrative bootstrap settings. It prepares cryptographic material, Cloudflare resources, generated Worker bindings, migrations, and deployment state.

Area	Current responsibilities
Workers	Protocol services, Router, Control, Plugin Runner, and selected UIs/features
Databases	Separate schema families for Core, PII, Admin, Control, Lookup, and Plugin Runner; managed capacity and routing rather than a fixed three-database recipe
Runtime routing	Signed registry documents, database binding identities, and generation information
Other resources	KV, Durable Objects, and enabled Queues/R2 resources
Local state	Environment configuration and deployment records under .authrim; keys in the configured key location, normally .authrim-keys

Follow the wizard through deployment and use the URLs it reports. Retain local configuration and keys securely for updates and recovery. Do not commit generated credentials or keys.

Inspect and deploy a configured environment

pnpm run setup status --env prod
pnpm run setup info --env prod
pnpm run setup config --validate --env prod
pnpm run setup deploy --env prod --dry-run

For a configured environment, deploy with:

pnpm run setup deploy --env prod

deploy is not a substitute for initializing a missing environment. Resolve configuration, resource, or migration errors before continuing.

Update an existing installation

From the intended release source, inspect the update first:

pnpm run setup update --env prod --dry-run
pnpm run setup update --env prod

Released installations use a finalized release migration manifest. Fresh-install baselines and upgrades are different plans; do not apply a new baseline to an existing database or manually concatenate migration files. The schema-family directories are migrations/core/, pii/, admin/, control/, lookup/, and plugin-runner/, with backend-specific subdirectories.

--allow-draft-manifest is a development option, not the normal installation or production-update procedure. If release artifacts are missing, use an appropriate released source rather than bypassing the check.

Local development

pnpm run dev starts the repository’s development tasks; it does not provision a complete local copy of a deployed environment. Multi-Worker bindings, databases, keys, and feature-specific dependencies still need a matching development configuration. Use the URLs printed by each development server rather than assuming all services share port 8787.

Troubleshooting

• Check the environment name and working directory with setup status and setup info.
• Check Cloudflare authentication and account permissions if resource creation fails.
• Keep generated bindings and registry state consistent; do not replace a missing tenant database with a shared binding.
• If the port used by a development server is occupied, stop that known server or choose another port. Avoid terminating unrelated processes.

Continue with Quickstart for discovery and your first client, or Architecture for the runtime layout.