{"id":26,"type":"docs","title":"Deployment Runbook: Heroku + Cloudflare","slug":"deployment-runbook-heroku-cloudflare","canonicalUrl":"https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Operations > Deployment","topics":["Heroku","Cloudflare","Deployment","Operations"],"tags":["heroku","cloudflare","dns","ssl","production"],"related":[{"slug":"what-broke-deploying-nextjs-16-heroku","title":"What Broke When I Deployed Next.js 16 to Heroku","type":"blog","canonicalUrl":"https://docs.phatysd.me/content/what-broke-deploying-nextjs-16-heroku"},{"slug":"why-cloudflare-ssl-handshake-failed-525","title":"Why Cloudflare Returned SSL Handshake Failed 525","type":"blog","canonicalUrl":"https://docs.phatysd.me/content/why-cloudflare-ssl-handshake-failed-525"},{"slug":"authentication-runbook-gitlab-authjs","title":"Authentication Runbook: GitLab OAuth + Auth.js","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs"}],"body":"# Deployment Runbook: Heroku + Cloudflare\n\nThis 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.\n\n## Architecture\n\n```text\nBrowser\n  ↓ HTTPS\nCloudflare DNS/proxy and edge TLS\n  ↓ HTTPS to origin\nHeroku custom domain / router\n  ↓ PORT supplied by platform\nNext.js web dyno\n  ↓ DATABASE_URL over PostgreSQL SSL\nHeroku Postgres\n```\n\nCloudflare 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.\n\n## DNS and custom domain\n\n1. Add the custom domain to Heroku.\n2. Copy the exact Heroku DNS target returned by `heroku domains -a <APP>`.\n3. Create the matching CNAME in Cloudflare for the subdomain.\n4. Proxy the record only after the origin works directly and the origin certificate path is known.\n5. Keep one authoritative public hostname in `NEXT_PUBLIC_SITE_URL` and Auth.js `AUTH_URL`.\n\nDo not point the public site at an internal dyno port. Heroku router ports shown in logs are process details, not public addresses.\n\n## TLS and Cloudflare 525\n\nCloudflare 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.\n\nFor 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.\n\nUseful checks:\n\n```bash\ncurl -Iv https://docs.phatysd.me/\ncurl -I https://<HEROKU_APP>.herokuapp.com/\nheroku domains -a <APP>\nheroku certs -a <APP>\nheroku logs --tail -a <APP>\n```\n\nCompare timestamps between Cloudflare errors and Heroku logs. If Heroku sees no request, investigate DNS, TLS, and Cloudflare origin connectivity first.\n\n## Heroku configuration and build\n\nInspect variable names without printing values:\n\n```bash\nheroku 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()))'\n```\n\nTypical 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`.\n\n`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.\n\nVerify the production build locally where safe:\n\n```bash\nnpm run typecheck\nnpm run lint\nnpm run build\n```\n\nHeroku supplies `PORT`. The application must listen on that value; never hardcode the port printed by a dyno log.\n\n## Migrations and release safety\n\nRun 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.\n\nHeroku 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.\n\n```bash\nheroku releases -a <APP>\nheroku releases:info v<N> -a <APP>\nheroku rollback v<N> -a <APP>\n```\n\n## Production smoke test\n\nAfter every deployment, check:\n\n```bash\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/llms.txt\ncurl -fsS -o /dev/null -w '%{http_code}\\n' https://docs.phatysd.me/content/<slug>/json\n```\n\nThen check the OAuth redirect, database read, public canonical URL, sitemap, and logs. A successful Heroku build is only one part of the release gate.\n\n## Official references\n\n- [Cloudflare Error 525](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-525/)\n- [Cloudflare encryption modes](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/)\n- [Heroku config vars](https://devcenter.heroku.com/articles/config-vars)\n- [Heroku releases and rollback](https://devcenter.heroku.com/articles/releases)\n- [Heroku release phase](https://devcenter.heroku.com/articles/release-phase)\n- [Next.js deploying](https://nextjs.org/docs/app/getting-started/deploying)\n"}