Docker

## 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 | Concept | Meaning | |---|---| | Image | Immutable package built from a Dockerfile. | | Container | Running instance of an image. | | Multi-stage build | Dockerfile pattern that keeps build tools out of the final image. | | Standalone output | Minimal Next.js server output for self-hosting. | | Runtime env | Values 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 | Mistake | Why It Happens | Correct Approach | |---|---|---| | Copying the whole repo into runtime | Simpler Dockerfile feels easier. | Copy standalone output and static assets. | | Missing `.next/static` | Standalone output excludes static chunks. | Copy `.next/static` into the runtime image. | | Baking secrets into image | Env values are set during build. | Inject secrets at container runtime. | | Using Docker for local dev on every OS | File 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 | Feature | Browser Impact | Notes | |---|---|---| | Docker runtime | None directly | Browser sees normal HTTP output. | | Static chunks | Important | Must be copied and served correctly. | | Images and fonts | Depends on deployment | Confirm 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 | Task | Pattern | |---|---| | Smaller image | Multi-stage Dockerfile | | Minimal Next output | `output: "standalone"` | | Runtime secrets | `docker run --env-file` | | Static chunks | Copy `.next/static` | | Public assets | Copy `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.