ReviseAlgo Logo

Deployment

Docker

Learn how to package a Next.js application as a Docker container using production builds, standalone output, and runtime environment values.

1. Learning Objectives

By the end of this lesson, you will be able to explain when Docker makes sense for Next.js, configure standalone output, write a production Dockerfile, and avoid build-time environment traps.

Difficulty: Intermediate.

2. Prerequisites

  • Next.js production builds.
  • Basic Docker concepts.
  • Environment variable basics.

    • 3. Overview

    Docker packages an application and its runtime into an image that can run consistently across infrastructure. Next.js supports Docker deployments, and the common production pattern is to use output: "standalone" so the final image contains only the files needed to run the server.

    4. Why This Topic Matters

    Many teams deploy Next.js to container platforms such as Kubernetes, Cloud Run, ECS, Fly.io, or Render. Docker gives portability, but it also makes the distinction between build-time and runtime configuration more important.

    5. Real-World Analogy

    A Docker image is a sealed shipping container. It carries the app and its runtime, but the destination still injects environment-specific labels like database URLs and secrets.

    6. Core Concepts

    ConceptMeaning
    ImageImmutable package built from a Dockerfile.
    ContainerRunning instance of an image.
    Multi-stage buildDockerfile pattern that keeps build tools out of the final image.
    Standalone outputMinimal Next.js server output for self-hosting.
    Runtime envValues provided when the container starts.

    7. Syntax & API Reference

    8. Visual Diagram

    9. Live Example - Full Working Code

    What just happened? The dependency and build stages create the production output. The runner stage copies only the standalone server, static files, and public assets needed to run.

    10. Interactive Playground

    Try this:

  • Add output: "standalone" to a sample app.
  • Build the image.
  • Run it with an env file.
  • Confirm the app responds on port 3000.

    • 11. Common Mistakes

    MistakeWhy It HappensCorrect Approach
    Copying the whole repo into runtimeSimpler Dockerfile feels easier.Copy standalone output and static assets.
    Missing .next/staticStandalone output excludes static chunks.Copy .next/static into the runtime image.
    Baking secrets into imageEnv values are set during build.Inject secrets at container runtime.
    Using Docker for local dev on every OSFile sync can be slow on Mac/Windows.Prefer npm run dev locally unless Docker is required.

    12. Best Practices

  • Use multi-stage Dockerfiles.
  • Use standalone output for smaller runtime images.
  • Keep .dockerignore strict.
  • Pass secrets at runtime.
  • Use a health check in production infrastructure.

    • 13. Browser Compatibility

    FeatureBrowser ImpactNotes
    Docker runtimeNone directlyBrowser sees normal HTTP output.
    Static chunksImportantMust be copied and served correctly.
    Images and fontsDepends on deploymentConfirm optimization support for your host.

    14. Interview Questions

    Easy: What is a Docker image?

    Answer: An immutable package containing application files and runtime instructions.

    Medium: Why use output: "standalone" for Docker?

    Answer: It produces a minimal server bundle with traced dependencies, reducing what must be copied into the runtime image.

    Hard: Why can Docker expose env-var bugs in Next.js?

    Answer: Public env vars are often inlined at build time, while server runtime values can be injected when the container starts. Mixing the two causes stale or missing values.

    15. Debugging Exercise

    Bug report: "The Docker container starts, but all CSS and JS chunks return 404."

    Solution

    The image probably copied .next/standalone but not .next/static. Copy .next/static to ./.next/static in the runtime stage.

    16. Practice Exercises

  • Easy: Explain image vs container.
  • Medium: Add output: "standalone" to a Next.js config.
  • Hard: Write a multi-stage Dockerfile for a Next.js app with runtime env vars.

    • 17. Scenario-Based Challenge

    Your team wants one Docker image promoted from staging to production. How should environment variables be handled?

    Walkthrough

    Keep server-only values runtime-driven and inject them per environment. Avoid relying on NEXT_PUBLIC_ values for promotion-sensitive settings because they are inlined during build.

    18. Quick Quiz

    1. What file defines Docker build steps? Answer: Dockerfile. 2. What config creates minimal Next.js server output? Answer: output: "standalone". 3. What directory contains static chunks? Answer: .next/static. 4. Should production secrets be copied into an image? Answer: No. 5. What command runs a container image? Answer: docker run.

    19. Summary & Key Takeaways

  • Docker makes Next.js portable across container infrastructure.
  • Standalone output keeps runtime images smaller.
  • Static assets must be copied alongside the standalone server.
  • Runtime env vars are central to reusable images.
  • Public env vars are build-time values.

    • 20. Cheat Sheet

    TaskPattern
    Smaller imageMulti-stage Dockerfile
    Minimal Next outputoutput: "standalone"
    Runtime secretsdocker run --env-file
    Static chunksCopy .next/static
    Public assetsCopy public

    21. Further Reading

  • Next.js Docs: Deploying.
  • Next.js Docs: Self-Hosting.
  • Docker Docs: Containerize a Next.js application.

    • 22. Next Lesson Preview

    Next, you will learn how environment variables behave across local development, builds, browsers, servers, and deployment platforms.