Docker: Containerize Your Next.js and Node App

Concept

Docker is a tool that packs your application and everything it needs into one package called an image. That includes the exact Node version, the libraries, the system tools and the start command. Any computer with Docker can run the image and get exactly the same behaviour. This works on your laptop, your teammate's Windows PC, a CI server (a machine that builds and tests your code automatically) and an EC2 instance.

Why this matters

In Lesson 7 you set up a server by hand: install Node, clone, build, PM2. It worked. But look at what you made: a server that only you know how to rebuild.

• “Works on my machine.” Your laptop has Node 22.3 and the server has 22.11, so a native module (code written in C or C++ that Node loads) behaves differently. Docker removes the difference: the same image runs everywhere.
• Slow setup with many mistakes. A new server means repeating 20 manual steps. With Docker you write the steps once, in the Dockerfile.
• Auto Scaling needs it. Lesson 12 creates servers automatically when traffic grows. A new server must be ready with no human steps. “Install Docker, pull the image, run it” is only three commands.
• Easy rollback. Every release is an image with a version. To roll back (go back to the old version), you run the previous tag.
• Build once, ship the result. The build happens in CI, not on the production server that is busy serving customers.

Image, container, registry — the three words

Remember this chain: Dockerfile → (build) → Image → (run) → Container. In one line: an image is the frozen package, and a container is that package running. Images move between machines through a registry. Build once, push the image to the registry, then pull it on any machine.

A tag is a label on an image, such as myapp:1.0.0. The part before the colon is the name, and the part after it is the version.

Container vs virtual machine

A virtual machine (VM) is a whole pretend computer, with its own operating system, running on real hardware. Your EC2 instance is a virtual machine. A container is lighter. It shares the host's operating-system kernel and only separates a process and its files from the others.

They work together, not against each other: containers run on top of EC2. AWS also has services that run containers for you (ECS, EKS and App Runner; see Lesson 19). Writing a good image is the same skill for all of them.

Install Docker

On your laptop

Install Docker Desktop (Mac, Windows) or Docker Engine (Linux). Docker Engine is the background program that builds and runs containers. On Windows, use the WSL 2 backend (Linux inside Windows) from Lesson 1. Then check that it works:

On the Ubuntu EC2 server

Follow Docker's own “Install Docker Engine on Ubuntu” page. It adds Docker's signed package source, then installs the engine and the Compose plugin. Afterwards, add the ubuntu user to the docker group, so that you do not need sudo each time. Then log out and log in again.

Your first containers

The other commands are easy to guess. You can list running containers (docker ps), follow a container's logs (docker logs, where the app's output goes), open a shell inside it (docker exec -it), stop it (docker stop) and remove it (docker rm). Removing a container keeps its image on disk for next time.

Port mapping confuses everyone at first. -p 8080:80 means host port : container port. The container has its own private network. Without -p, nothing outside can reach it. The number on the left is the door on your machine that a visitor uses.

Layers and the build cache

An image is a stack of layers. A layer is one saved step of the build. Instructions that change files (RUN, COPY, ADD) each make a layer. Docker keeps each layer in a cache (a store of earlier results). It reuses a layer if its instruction and everything before it did not change. This one fact explains most Dockerfile advice.

# SLOW: any code change makes the COPY layer new, so npm install runs again every time
COPY . .
RUN npm install

# FAST: dependencies change rarely and code changes often, so put the rarely-changing step first
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile     # cached until the lockfile changes
COPY . .                               # only this layer rebuilds on a code change

Rule: put what changes least at the top and what changes most at the bottom. A rebuild that uses the cache takes seconds. One without the cache takes minutes.

A production Dockerfile for Next.js

First turn on Next.js's standalone output. It finds exactly which files the server needs and copies only those. This can shrink the app files a lot, so the image is often a few hundred MB instead of over 1 GB:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Now the Dockerfile. It is a multi-stage build: one Dockerfile with several steps (stages), where only the last stage becomes the final image. Read it from top to bottom:

# ---------- Stage 1: install dependencies ----------
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# ---------- Stage 2: build the app ----------
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN corepack enable && pnpm build

# ---------- Stage 3: the small image we actually ship ----------
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME=0.0.0.0

# A normal user, not root
RUN addgroup -S app && adduser -S app -G app

# Copy ONLY the output. No source, no dev dependencies, no build tools.
COPY --from=build --chown=app:app /app/.next/standalone ./
COPY --from=build --chown=app:app /app/.next/static ./.next/static
COPY --from=build --chown=app:app /app/public ./public

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

Reading it line by line

The .dockerignore file — do not skip it

COPY . . copies everything in the folder. The .dockerignore file tells Docker what to leave out. Without it, your .env secrets, your .git history and a 1 GB local node_modules go into the build.

node_modules
.next
.git
.env*
*.pem

Build it and run it

Config, secrets, ports and data

Docker Compose — the whole stack in one file

Real apps use several containers: the app, a database, and later Redis (a fast in-memory data store). Docker Compose is a tool that describes all of them in one file and starts them with one command. It is the standard tool for local development and for simple single-server setups.

services:
  app:
    build: .
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgresql://appuser:devpass@db:5432/myapp   # host is the SERVICE NAME "db"
    depends_on: [db]

  db:
    image: postgres:16
    environment: { POSTGRES_USER: appuser, POSTGRES_PASSWORD: devpass, POSTGRES_DB: myapp }
    volumes: [pgdata:/var/lib/postgresql/data]   # data survives `docker compose down`

volumes:
  pgdata:

docker compose up -d builds and starts everything in the background. docker compose down stops and removes the containers, but it keeps the data volume. Add -v to delete the data too.

In production, do not put the database in Compose. Use RDS (Lesson 8) and set DATABASE_URL to its endpoint. The dev compose file above is close enough to production to catch mistakes, and it costs nothing.

Run it on EC2

Here the twenty manual steps of Lesson 7 shrink to a few. Once Docker is installed on the server, deploying means pull and run. (This time we copy the image to the server by hand. The next sections use a registry, which is the proper way.)

Put the production variables in ~/myapp.env on the server. Set its permissions to 600, and never put it in Git or in the image. Then run:

docker run -d --name myapp \
  --restart unless-stopped \
  --env-file ~/myapp.env \
  -p 127.0.0.1:3000:3000 \
  --memory 1g \
  --log-opt max-size=10m --log-opt max-file=3 \
  myapp:1.0.0

Each flag earns its place:

• --restart unless-stopped replaces PM2. Docker starts the container again after a crash and after a reboot.
• -p 127.0.0.1:3000:3000 opens the port only on the server's loopback address (127.0.0.1, which only the server itself can reach). Nginx (Lesson 10) can reach it, and the internet cannot. Plain -p 3000:3000 listens on every interface. Docker also changes the firewall rules by itself, so the port can be open to the world even if you thought a firewall rule blocked it.
• --memory 1g limits memory. If the app leaks memory, only one container restarts and the whole server does not run out of memory.
• --log-opt max-size stops the JSON log files from quietly filling the disk. This is a common cause of outages.

Registries and ECR

“Copy the image to the server” does not work for many servers. A registry is the standard hand-over point. CI pushes an image, and every server pulls it. AWS's own registry is ECR (Elastic Container Registry). It is private by default, works with IAM, and has no data transfer charge when you pull from inside the same region.

The flow has three steps. You can do them from your laptop or (later) from CI:

1. Create a private repository in ECR named myapp. Turn on scan on push, so every image is checked for known vulnerabilities (security holes that are already public).
2. Log Docker in to ECR with a temporary token from the AWS CLI. The token lasts 12 hours.
3. Build the image, tag it with the Git commit (myapp:a1b2c3d), and push it.

You do not need to memorise the exact commands. The View push commands button in the ECR console shows them, already filled in with your account and region.

On the server, the role from Lesson 5 needs permission to pull images. Attach the AWS-managed policy AmazonEC2ContainerRegistryReadOnly to myapp-ec2-role. The server then logs in and pulls in the same way, using the role and no keys.

Debugging containers

Ten mistakes to skip

Interview corner

Practice task before Lesson 10

1. Add output: "standalone", the Dockerfile and .dockerignore to your Next.js repo. Build it and run it locally. Note the image size.
2. Change one line of source, rebuild, and watch which steps say CACHED. Then change a dependency and see the difference.
3. Write a docker-compose.yml with your app and Postgres. Run the app, create a row, run docker compose down then up and confirm the row survived. Then run down -v and confirm it did not.
4. Create the ECR repository, push an image tagged with your Git SHA, and confirm it in the console. Read the scan results.
5. On the EC2 server: install Docker, remove the app from PM2, pull your image and run it with the flags from this lesson. Confirm it survives sudo reboot.
6. Explain in two sentences why -p 127.0.0.1:3000:3000 is safer than -p 3000:3000.

Conclusion

Docker turns “a server only you can rebuild” into “an image anyone can run”. It is the link between the manual work of Lesson 7 and the automation of Lessons 12–15.

• Dockerfile → image → container. Registry to move images between machines.
• Layer order = build speed. Lockfile and install first, source last.
• Ship small and safe: use a multi-stage build, standalone output, a non-root user and a proper .dockerignore.
• Give config at run time, never inside the image. Take secrets from the environment or a secret store, and get AWS access from the IAM role.
• Containers are disposable. State lives in RDS and S3; fixes go into the Dockerfile; tags are commit SHAs.

The app now runs in a container that listens on a private port. Next we put a proper receptionist in front of it: Nginx (a web server that receives requests and passes them to your app).

End of Lesson 9. Next: Lesson 10 — Nginx: Reverse Proxy.