Docs · Web Blog / Operations / Deployment
Deployment Runbook: Heroku + Cloudflare
Deployment Runbook: Heroku + Cloudflare
This runbook describes the production path for a Next.js application hosted on Heroku and exposed through a Cloudflare-managed custom domain. Use placeholders in commands; never paste real credentials into shell history, tickets, or agent transcripts.
Architecture
Browser
↓ HTTPS
Cloudflare DNS/proxy and edge TLS
↓ HTTPS to origin
Heroku custom domain / router
↓ PORT supplied by platform
Next.js web dyno
↓ DATABASE_URL over PostgreSQL SSL
Heroku Postgres
Cloudflare terminates the visitor connection and also creates a second connection to the origin. A green browser lock does not prove that Cloudflare can complete the origin handshake.
DNS and custom domain
- Add the custom domain to Heroku.
- Copy the exact Heroku DNS target returned by
heroku domains -a <APP>. - Create the matching CNAME in Cloudflare for the subdomain.
- Proxy the record only after the origin works directly and the origin certificate path is known.
- Keep one authoritative public hostname in
NEXT_PUBLIC_SITE_URLand Auth.jsAUTH_URL.
Do not point the public site at an internal dyno port. Heroku router ports shown in logs are process details, not public addresses.
TLS and Cloudflare 525
Cloudflare Error 525 means the TLS handshake between Cloudflare and the origin failed. Common causes are an invalid or missing origin certificate, port 443 problems, SNI problems, or incompatible cipher suites. The Cloudflare-to-origin mode must match the origin capability.
For a normal HTTPS Heroku origin, use Full or Full (strict) only when the origin certificate and hostname validation are correct. Avoid Flexible as a permanent fix: it encrypts the visitor-to-Cloudflare leg but uses HTTP from Cloudflare to the origin.
Useful checks:
curl -Iv https://docs.phatysd.me/
curl -I https://<HEROKU_APP>.herokuapp.com/
heroku domains -a <APP>
heroku certs -a <APP>
heroku logs --tail -a <APP>
Compare timestamps between Cloudflare errors and Heroku logs. If Heroku sees no request, investigate DNS, TLS, and Cloudflare origin connectivity first.
Heroku configuration and build
Inspect variable names without printing values:
heroku config -a <APP> --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(Object.keys(JSON.parse(s)).sort()))'
Typical names for this project are DATABASE_URL, AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST, AUTH_GITLAB_ID, AUTH_GITLAB_SECRET, AUTH_GITLAB_OWNER_USERNAME, and NEXT_PUBLIC_SITE_URL.
NEXT_PUBLIC_* values can be bundled at build time. Set them before the build when the compiled application needs them, then deploy a fresh release. A config change creates a Heroku release and restarts the app, but a public variable already embedded in a build may require a rebuild to change generated canonical URLs.
Verify the production build locally where safe:
npm run typecheck
npm run lint
npm run build
Heroku supplies PORT. The application must listen on that value; never hardcode the port printed by a dyno log.
Migrations and release safety
Run reviewed database migrations as a release step or controlled one-off operation. Make them retry-safe and avoid destructive data changes in the same release as an unverified schema change. Do not run npm run db:seed against production by accident.
Heroku creates releases for code, config changes, and add-on changes. Use release history to identify what changed. Prefer a code fix and redeploy; use rollback for an urgent platform/config failure, remembering that rollback does not undo external database state.
heroku releases -a <APP>
heroku releases:info v<N> -a <APP>
heroku rollback v<N> -a <APP>
Production smoke test
After every deployment, check:
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/llms.txt
curl -fsS -o /dev/null -w '%{http_code}\n' https://docs.phatysd.me/content/<slug>/json
Then check the OAuth redirect, database read, public canonical URL, sitemap, and logs. A successful Heroku build is only one part of the release gate.
Official references
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.