---
id: 26
type: docs
title: "Deployment Runbook: Heroku + Cloudflare"
slug: "deployment-runbook-heroku-cloudflare"
canonical_url: "https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "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
    canonical_url: "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
    canonical_url: "https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs"
---

# 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

```text
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

1. Add the custom domain to Heroku.
2. Copy the exact Heroku DNS target returned by `heroku domains -a <APP>`.
3. Create the matching CNAME in Cloudflare for the subdomain.
4. Proxy the record only after the origin works directly and the origin certificate path is known.
5. Keep one authoritative public hostname in `NEXT_PUBLIC_SITE_URL` and Auth.js `AUTH_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:

```bash
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:

```bash
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:

```bash
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.

```bash
heroku releases -a <APP>
heroku releases:info v<N> -a <APP>
heroku rollback v<N> -a <APP>
```

## Production smoke test

After every deployment, check:

```bash
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

- [Cloudflare Error 525](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-525/)
- [Cloudflare encryption modes](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/)
- [Heroku config vars](https://devcenter.heroku.com/articles/config-vars)
- [Heroku releases and rollback](https://devcenter.heroku.com/articles/releases)
- [Heroku release phase](https://devcenter.heroku.com/articles/release-phase)
- [Next.js deploying](https://nextjs.org/docs/app/getting-started/deploying)
