Deploying your own copy

From a clone to a running builder. The repository’s own apps/web/README.md carries the exact commands and stays with the code, so it is the version to follow; this page is the shape of the job and the parts that bite.

The order that works

1. Create the stored state first. A D1 database and an R2 bucket, both named in the Worker’s configuration. The Durable Object and the Workflow need no provisioning.
2. Apply the migrations before deploying the Worker, not after. This one is not a style preference: shipping a Worker whose code expects a table that does not exist yet takes the whole thing down, and it has happened here. Two migrations once sat unapplied for two days and every generation failed with an accounting error until somebody applied them by hand.
3. Deploy the sandbox and publish Workers, and set the two shared secrets on both sides of each pair.
4. Deploy the builder with its service bindings pointing at those two.

Migrations are idempotent, so applying them when there is nothing new is a no-op. Make it a step in your deploy rather than something you remember.

The domain problem, which will catch you

A live Clerk instance is bound to a domain, and Clerk’s Frontend API refuses any request whose origin is not that domain or a subdomain of it. A deployment reachable only at a workers.dev URL will therefore not load Clerk at all, which looks like a broken sign-in rather than a configuration mismatch.

Two ways through it:

• Use a development Clerk instance while you are standing things up, and switch when you have a domain.
• Or put the Worker on a custom domain from the start. A custom domain route provisions its own DNS record on deploy, but only if the deploying token can manage DNS on that zone. A token scoped to Workers alone is not enough, and the failure at deploy time does not say so very clearly.

Adding a custom domain also disables that Worker’s workers.dev address entirely, so the old URL starts returning 404 rather than continuing to work alongside the new one.

What to check once it is up

• Sign in. If the sign-in page never renders, it is the domain problem above, not your Clerk keys.
• Run one generation. If it refuses, the provider key and VIBLD_PROVIDER disagree, or the spend ledger has no Durable Object binding.
• Start one sandbox. If it reports itself unavailable rather than failing, the service binding or the shared secret is missing on one of the two sides.

Each of those refuses rather than half-working, which is the point: you will get an unavailable feature and a reason, not a deployment that looks fine until it spends money incorrectly.

Where the exact commands live

In the repository, beside the code they deploy: apps/web/README.md. Keeping them there rather than duplicating them here is deliberate. A command on a marketing page ages badly and nobody notices.