Going to production
This is the last stage, and the one to take slowly. Production is the only Runtime Context that carries your domain, indexes in search engines, and charges real money.
flowchart LR
L["1. Local setup<br/>Both apps on your machine"] --> D["2. Deploying development<br/>A push deploys"]
L --> R["3. Adding pull request previews<br/>Independent of development"]
D --> S["4. Adding staging<br/>Optional"]
S --> P["**5. Going to production**<br/>Your domain, real users"]
D -. "without staging" .-> P
Do this once the application is the product you want people to see, and once its name is final.
PROJECT_SLUG is inside every Worker, bucket, database and pool name, so renaming the project after
launch creates new, empty resources and leaves production's data behind in the old ones —
Renaming your project says what that costs.
Nothing on this page is reversible for free either: a search engine that indexes a half-finished
site keeps the result, and a Polar production token moves real money.
main deploys it. Production's values
ship empty, so a push to main before this page is done fails, naming the first one missing.Prerequisites
Gather all of these before you run a command. Each one is a console you'd otherwise open in the middle of a step.
What you need before you start
| You need | How to get it | Required |
|---|---|---|
| Deploying development finished | development deploying | Yes |
A final PROJECT_SLUG | The name you keep, in .env.project.schema | Yes |
| Your zone active in Cloudflare | Add PROJECT_ZONE as a zone and move its nameservers, so a Custom Domain can attach | Yes |
| A production Postgres | A managed instance of its own — never one another context uses | Yes |
| A production Google OAuth client | Set up sign-in and payments — a separate client | Only for Google sign-in |
| A production GitHub OAuth app | Same page — a separate app, one callback URL per origin | Only for GitHub sign-in |
| A Polar production organization and token | Same page, from the production dashboard rather than the sandbox | Only for payments |
A fresh NUXT_APP_SECRET | openssl rand -base64 32 — its own value, never another context's | Yes |
A main branch | Your clone has one, and production deploys from it | Yes |
Decide your production hostnames
PROJECT_DOMAIN decides where both applications answer and where their mail comes from. It defaults
to PROJECT_ZONE, which is the answer when your project owns a whole zone. Set it only when the
project lives at a subdomain of a zone you use for other things.
| What you set | apps/site serves | apps/web serves |
|---|---|---|
| Nothing — the domain is the zone | example.com | app.example.com |
PROJECT_DOMAIN=my-app.example.com | my-app.example.com | app.my-app.example.com |
Worked scenarios has the full table, including
the case where your slug and your domain are different words, and the two topologies that need you to
write CLOUDFLARE_WORKER_ROUTE by hand.
The production Secret Tier
Every key below lives in apps/web's Infisical project, environment production, path /.
Production is the one tier where a stand-in is worse than a missing value: a stand-in in a credential
lets the build succeed and fails at a real user's first sign-in instead. Use one only for a feature
you aren't offering.
| Key | Comes from | Needed for |
|---|---|---|
DATABASE_URL | Your production Postgres | Every request — the deploy points production's Hyperdrive configuration at it |
NUXT_APP_SECRET | openssl rand -base64 32 | Every sign-in (@app/layer-auth) |
GOOGLE_CLIENT_SECRET | Your production Google client | Google sign-in (@app/layer-auth) |
GITHUB_CLIENT_SECRET | Your production GitHub app | GitHub sign-in (@app/layer-auth) |
POLAR_ACCESS_TOKEN | The Polar production dashboard | Payments (@app/layer-payments) |
POLAR_WEBHOOK_SECRET | Your production Polar webhook | Payments (@app/layer-payments) |
NUXT_EMAIL_PLATFORM_ADMIN_EMAILS | Addresses you choose | Platform alerts (@app/layer-email). Optional — leave it empty to turn them off |
Set them together, with the project id committed in apps/web/.env.infisical:
infisical secrets set \
DATABASE_URL='<production connection string>' \
NUXT_APP_SECRET="$(openssl rand -base64 32)" \
GOOGLE_CLIENT_SECRET='<production Google client secret>' \
GITHUB_CLIENT_SECRET='<production GitHub client secret>' \
POLAR_ACCESS_TOKEN='<production Polar token>' \
POLAR_WEBHOOK_SECRET='<production Polar webhook secret>' \
--env=production --path=/ --projectId='<apps/web project id>'
Check they landed. infisical secrets prints values in full, so send it through jq and emit the
key names alone:
out=$(infisical secrets --projectId='<apps/web project id>' \
--env=production --path=/ --output=json --silent)
printf '%s' "$out" | jq -r '.[].secretKey' | sort
infisical secrets puts every production credential on
your screen, into your scrollback, and into any terminal recording or CI log. Capture to a variable
and print only what you need.Register the production callback URLs
One callback URL per exact origin, on the production OAuth applications rather than the ones another context uses:
| Provider | Callback URL |
|---|---|
https://app.<domain>/api/auth/callback/google | |
| GitHub | https://app.<domain>/api/auth/callback/github |
| Polar | https://app.<domain>/api/webhooks/polar |
Configure and deploy
Set PROJECT_DOMAIN if it isn't your zone
Leave it alone when your project owns the whole zone. Otherwise:
PROJECT_DOMAIN=my-app.example.com
Both production routes and both production sending domains follow this one line.
Write production's origins
No origin is derived, and production's has to agree with its route. CLOUDFLARE_WORKER_ROUTE is
already built from PROJECT_DOMAIN, so in most projects you write only the origins. They ship
empty, and a push to main fails naming them until you write them:
NUXT_PUBLIC_APP_BASE_URL=https://app.<domain>
NUXT_PUBLIC_APP_WEBSITE_BASE_URL=https://<domain>
NUXT_PUBLIC_APP_BASE_URL=https://<domain>
CLOUDFLARE_WORKER_ROUTE decides where the Worker answers; NUXT_PUBLIC_APP_BASE_URL is
baked into the bundle and reaches your canonical tags, social images, sitemap and email. A mismatch
serves one hostname and advertises another. apps/web's NUXT_PUBLIC_APP_WEBSITE_BASE_URL must
point at the site's origin, or its links to /docs and /blog 404.Attaching a domain covers the two route shapes, and
the path-scoped one that also needs CLOUDFLARE_WORKER_ROUTE_ZONE.
Fill in the rest of the production value files
Two keys flip in production and nowhere else, and both are already set in the files you inherited. Confirm rather than change them:
| Setting | Ships as | Why |
|---|---|---|
NUXT_PUBLIC_SITE_INDEXABLE | true | The one context search engines should find |
POLAR_SERVER | production | Needs the production Polar token, not a sandbox one |
These are yours:
| Setting | What to put in |
|---|---|
GOOGLE_CLIENT_ID | Your production Google client id — a client id isn't secret |
GITHUB_CLIENT_ID | Your production GitHub client id |
NUXT_PUBLIC_CONTACT_EMAIL | In apps/site/.env.production, the address your site publishes |
Each of these ships empty and the schema marks it required, so a resolution stops on it by name. A sign-in provider you aren't offering takes a stand-in in its client id. Why some credentials are committed explains why a client id lives in Git and a client secret doesn't.
Onboard the production sending domains
Production is the one context whose senders carry your domain rather than your slug:
| Application | Sends from |
|---|---|
apps/web | app.<domain> |
apps/site | site.<domain> |
app.<domain> is also apps/web's Worker route, and that's not a collision — a Custom Domain is a
proxied address record, and the SPF and DKIM records live at the same name alongside it.
Read each hostname off the resolved environment rather than assembling it:
cd apps/web && APP_RUNTIME_CONTEXT=production pnpm exec varlock load --filter NUXT_EMAIL_SENDER_DOMAIN
Then onboard it and fetch its records:
pnpm exec wrangler email sending enable app.acme.com
pnpm exec wrangler email sending dns get app.acme.com
Repeat for apps/site. When your zone is in the same Cloudflare account the records are added for
you — confirm with wrangler email sending list.
Delete your registrar's parking records
Adding a zone to Cloudflare can import your registrar's parking A records on @, *, and www.
In your zone's DNS → Records, delete any that are there before the first push to main. A
record already on a Custom Domain's hostname stops that Custom Domain attaching.
Redirect HTTP to HTTPS
A Custom Domain answers plain http:// with a 200 instead of upgrading it. In your zone's
SSL/TLS → Edge Certificates, turn
Always Use HTTPS
on. It's one toggle for every hostname in the zone, so no Redirect Rule is needed.
Leave HSTS off for now. Browsers cache it, so a wrong setting is hard to take back. Turn it on later, as its own deliberate step.
Turn on Image Transformations
In production, @nuxt/image resizes every image it renders, avatars and blog covers included, at a
/cdn-cgi/image/ URL on your own hostname. Cloudflare answers those URLs only on a zone with Image
Transformations on, and the deploy doesn't turn it on. Without it, every resized image returns 404.
In the Cloudflare dashboard, go to Images → Transformations, select your zone, and enable transformations for it. Cloudflare's Transformations overview has the same steps.
The free plan includes 5,000 unique transformations a month, where one image at one size is one
transformation. Past that, new sizes fail with error 9422 until you buy the Images Paid plan.
Cloudflare Images pricing has the current limits.
Redirect www to your domain
Skip this step when your project lives at a subdomain. When production serves your zone's apex, send
www.<domain> to it with a 301. Visitors who type www. still land, and search engines and
cookies see one canonical host.
A redirect runs only on a proxied hostname, and nothing serves www. Add a placeholder record in
DNS → Records:
| Type | Name | IPv6 address | Proxy status |
|---|---|---|---|
AAAA | www | 100:: | Proxied |
Then go to Rules → Overview, select Create rule → Redirect Rule, and pick the
Redirect from WWW to root template. It fills in everything below except Preserve query
string. Turn that on, or the redirect drops ?utm= and ?ref= parameters:
| Field | Value |
|---|---|
| When incoming requests match | Wildcard pattern |
| Request URL | https://www.* |
| Target URL | https://${1} |
| Status code | 301 |
| Preserve query string | On |
Select Deploy. The dashboard may warn that This rule may not apply to your traffic because
DNS may not be proxying www. That's a false positive: a proxied record answers on Cloudflare's IPv4
and IPv6 addresses whatever its type. Select Ignore and deploy rule anyway, and don't let it add
a second record.
A Custom Domain claims one exact hostname, so this rule never collides with the one on your apex.
The values come from Cloudflare's
redirect www to root example.
Promote to main
Commit everything above on development and push it. If you
added staging, merge development into staging, push, and
check the staging deployment first. Then promote to main:
git checkout main
git merge staging # without staging: git merge development
git push origin main
A push to main deploys production. The first one also creates production's own bucket, content
database and pool, each named <slug>-<app>-production and empty — nothing is shared with another
context. Resources has the table. Nothing enforces the order — the gate
reads only the branch pushed — so promote by merging forward and never commit straight to main.
Check that it worked
Check the first four with curl -sI <url>. It prints the status and the Location header without
following the redirect.
- Both hostnames answer, over HTTPS, on your own domain.
http://<domain>/andhttp://app.<domain>/answer with a301to the same URL overhttps://.https://www.<domain>/blog?ref=testanswers with a301tohttps://<domain>/blog?ref=test, if you added the redirect. Overhttp://it takes one hop more, tohttps://www.<domain>/…first, because Always Use HTTPS runs before the rule.https://app.<domain>/cdn-cgi/image/w=48/logo.pnganswers200with acf-resizedheader.https://<domain>/robots.txtallows indexing, and development's still doesn't.- Sign up with a real address and confirm the verification email arrives — not in spam.
- Sign in with Google and GitHub, if you wired them up.
- Run a checkout and confirm Polar shows it in the production dashboard.
When it does not work
| What you see | What to fix |
|---|---|
| A red run naming a key | That value is empty in apps/*/.env.production or in the production tier at / |
The run stops at Upsert the Cloudflare resources | Production's connection string isn't in the production tier at / |
Authentication error [code: 10000] at the deploy | The token's R2 permission — see The Cloudflare API token |
| The domain returns a Cloudflare error, not your app | The zone isn't active in the account, so the Custom Domain never attached |
| The deploy fails attaching a Custom Domain | A record already sits on that hostname, often a registrar's parking record — delete it in DNS → Records |
http:// answers 200 instead of 301 | Always Use HTTPS is off — SSL/TLS → Edge Certificates |
The www. redirect drops ?ref= | Preserve query string is off on the Redirect Rule |
Avatars show initials, or /cdn-cgi/image/ returns 404 | Image Transformations is off for your zone — Images → Transformations |
New image sizes fail with error 9422 | The month's free transformations are used up — buy the Images Paid plan |
curl: (6) Could not resolve host on a new record | Your resolver caches its NXDOMAIN — wait, or curl --resolve <host>:443:<ip> with an <ip> from dig +short @1.1.1.1 <host> |
| Sign-in redirects to a mismatch error | The production callback URL isn't registered on the production OAuth client |
| Mail sends but never arrives | That exact hostname isn't onboarded — wrangler email sending list |
| A checkout fails at the first API call | POLAR_ACCESS_TOKEN is a sandbox token |
Next steps
- Resources — what production's first push created, and how to delete a context's resources by hand
- Deploy pipeline — what each event does from here
- Getting updates — pull NuxtStart's later changes into your project
