Self-Host Next.js: Standalone Output, Docker and Env Vars

  output: "standalone" as const, // self-hosted Docker deploy — trims node_modules to only what server.js needs

One line turns the feature on. Everything else in this lesson follows from it: the build now writes a standalone folder with its own server.js, and the Dockerfile copies that folder instead of the whole project.

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

The runner stage copies three things: public, the standalone folder, and .next/static into the path where server.js expects it. The chown flags give the non-root user ownership of what it runs. The process then runs as a non-root user and starts with node server.js, not next start.

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME=0.0.0.0

PORT and HOSTNAME are the two variables the Next.js docs name for the standalone server. The docs show HOSTNAME set to 0.0.0.0 in their own example. Compose then publishes the container port on the loopback address only, so the reverse proxy is the way in.

function getGroqClient(): Groq {
  if (!groq) {
    const apiKey = process.env.GROQ_API_KEY;
    if (!apiKey) {
      throw new Error("GROQ_API_KEY environment variable is missing");
    }
    groq = new Groq({ apiKey });
  }
  return groq;

A server-only secret, read with no NEXT_PUBLIC prefix inside a function that runs while a request is handled, and failing loudly if it is missing. It never enters the browser bundle, and the container receives the value when it starts, not when the image is built.

    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://127.0.0.1:3000/robots.txt",
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

The check runs inside the container, so it targets the internal port. It asks for robots.txt, an existing cheap route that touches no database, instead of a new endpoint. The start period gives server.js time to boot before failures count, and three misses in a row mark the container unhealthy.

  cacheMaxMemorySize: 16 * 1024 * 1024,

The default in-memory cache is 50 MB, as the self-hosting guide states. This site lowers it, because nearly every route is prerendered at build time and read from disk, and the server shares a small machine. Tune it only after you have measured memory.