Nginx Reverse Proxy With Docker Compose, Behind Cloudflare

    ports:
      # Bind to loopback only — nginx terminates TLS and proxies to this port.
      - "127.0.0.1:${APP_PORT:-3002}:3000"

The whole contract between the proxy and the app. Container port 3000 is published on the host's loopback only, at APP_PORT, so the only way in from outside is through nginx. The port number comes from .env, which the deploy writes.

      {
        source: "/images/(.*)",
        headers: [
          {
            key: "Cache-Control",
            value: "public, max-age=31536000, immutable",
          }, // Cache images for 1 year
        ],
      },

The app, not nginx, decides the cache policy, and the proxy and the CDN pass it along. Note what the rule matches: every path under /images/, including one that turns out to be a 404. What breaks, below, covers why that matters.

      // Production only. Build chunks are content-hashed there, so a year of
      // immutable caching is safe. Turbopack's dev chunks keep the same name
      // across edits, and this header in development made browsers keep
      // running stale game code for as long as their cache lived — the
      // "sometimes WASD stops working" reports were a mix of old and new
      // modules, not the controller.
      ...(process.env.NODE_ENV === "production"
        ? [
            {
              source: "/_next/static/(.*)",
              headers: [
                {
                  key: "Cache-Control",
                  value: "public, max-age=31536000, immutable",
                }, // Cache static assets for 1 year
              ],
            },
          ]
        : []),

immutable is a promise that the bytes behind a URL never change. In production that is true, because chunk names carry a content hash. In development it was false, and browsers kept running old code; the comment records the bug that taught it.

      {
        // The films, their posters and captions. A re-render keeps the file
        // names, so only a request carrying the render stamp
        // (lib/film-manifest.ts prints `?v=` on every URL) may be cached as
        // immutable; Cloudflare then serves the films from its edge. A bare
        // URL, from an old link, keeps revalidating against the origin.
        source: "/videos/:path*",
        has: [{ type: "query", key: "v" }],
        headers: [
          {
            key: "Cache-Control",
            value: "public, max-age=31536000, immutable",
          },
        ],
      },

Cache busting when the file name cannot change. The has condition makes the year-long header apply only to URLs with a ?v= stamp, so a re-render gets a new URL and an old bare link still revalidates.

/**
 * Every page answers in two representations at the same URL: HTML for
 * browsers, Markdown for agents that ask for it with `Accept: text/markdown`
 * (rendered by app/agent-md from the site's own data). Markdown requests are
 * rewritten before the locale middleware, so they get 200 at the URL they
 * asked for instead of a locale redirect, and carry `Vary: Accept`.
 *
 * Everything else goes through next-intl as before. Its locale redirects get
 * `Vary: Accept` here too; a rendered HTML page does not, because Next's App
 * Router page handler replaces the Vary header at render time (setHeader in
 * build/templates/app-page.js). Nothing caches in front of the site today;
 * if a shared cache is ever added, add `Vary: Accept` in nginx instead.
 */
export default function middleware(request: NextRequest): NextResponse {
  if (prefersMarkdown(request.headers.get("accept"))) {
    const url = request.nextUrl.clone();
    url.pathname = `${MARKDOWN_ROUTE}${request.nextUrl.pathname}`;
    return NextResponse.rewrite(url);
  }
  const response = intlMiddleware(request);
  response.headers.append("Vary", "Accept");
  return response;
}

Content negotiation at one URL. Markdown requests are rewritten to their own route and carry Vary: Accept; HTML pages cannot carry it. One line here is out of date: Cloudflare has proxied www since 2026-10-12, so something does cache in front of the site now. The conclusion still holds because the edge never stores HTML.