Containerize Your App

Containerizing means packaging your app and its environment into an imageImageA packaged, read-only snapshot of your app plus everything it needs to run: code, runtime, and libraries. You build it once and run it as many times as you like., so it runs the same way on any machine with Docker. The containerContainerA running instance of an image, isolated from your machine and from other containers. Think of it as a sealed box with your app inside. carries its own runtimeRuntimeThe program that actually executes your code, such as Node.js for JavaScript. A container bundles the exact runtime your app expects. (the program that runs your code, like Node.js), its dependenciesDependenciesThe external packages your app needs to run, like the ones in node_modules. Docker installs them into the image so they ship with the app. (the packages in node_modules), and the system librariesSystem librariesLower-level pieces the operating system provides that your app or its packages rely on, such as the library that handles HTTPS. They can differ between machines, which is one reason containers exist. the operating system provides, so it no longer matters what's installed on the hostHost machineThe computer Docker runs on: your laptop in development, a server in production. Containers are isolated from the host unless you connect them on purpose..

You describe that environment in a DockerfileDockerfileA text file listing the setup steps to build an image, one instruction per line. It is a recipe, not the finished meal., build it into an image, and run the image as a container.

Writing a Dockerfile

Think about what you'd do to run this app on a brand-new machine: install Node, make a project folder, copy in the package files, run npm install, copy in the source, start the serverServerA long-running program that waits for requests and responds to them, like a Node API. It is the kind of program you typically put in a container.. A Dockerfile is exactly that list of setup steps, written down so Docker can replay them. Each instruction builds on the one before, every instruction creates a layerLayerA snapshot Docker saves after each Dockerfile instruction. Stacked together, the layers form the final image., and Docker caches layers it has already built.

# Start from an official Node image
FROMFROMSets the base image your build starts from, like FROM node:20-alpine. It is always the first instruction and runs at build time. node:20-alpine

# All following commands run inside this directory
WORKDIRWORKDIRSets the directory that the following instructions run in, and creates it if needed. Think of it as cd-ing into your project folder, except it sticks for the rest of the build and the running container. /app

# Copy package files first, on their own, so npm install is cached
COPYCOPYCopies files from your project into the image. Copying package files on their own first lets Docker cache the dependency install separately from your source code. package*.json ./
RUNRUNRuns a command while the image is being built and bakes the result into a layer, like RUN npm install. Do not confuse it with CMD, which runs later. npm install

# Now copy the rest of the source
COPYCOPYCopies files from your project into the image. Copying package files on their own first lets Docker cache the dependency install separately from your source code. . .

# Documentation only — has no impact on the container's behavior at runtime
EXPOSEEXPOSEDocuments which port the app listens on. It does not open anything by itself: you still publish the port with docker run -p to reach the app. 3000

# The command that runs when the container starts
CMDCMDThe command that runs when a container starts, like CMD ["node", "server.js"]. Unlike RUN it executes nothing at build time, and you can override it at launch. ["node", "server.js"]

Dockerfile commands at a high level

A Dockerfile is a small set of instructions, each one a command in uppercase followed by its arguments. The example above uses six of them. Hover any highlighted keyword in the Dockerfile to see what it does, then use the table below as a quick reference for what each command does and when it runs. One detail worth noting on the first line: the -alpineAlpineA very small Linux distribution (the operating system inside the container). The -alpine image variants are stripped down so images download and start faster. tagTagThe label after the colon in an image name that pins a version, like the 20 in node:20. It tells Docker exactly which variant to use. picks a minimal base variant that keeps the image small.

At a glance, the six commands and when each takes effect:

Order your layers by how often they change

Copying package*.json and running npm install before copying your source is deliberate. Docker reuses a cached layer until one of its inputs changes. Your source changes on every edit; your dependencies rarely do. Put the rarely-changing step first and Docker skips reinstalling every package on each rebuild. This is layer cachingLayer cachingDocker reuses a saved layer until one of its inputs changes. Ordering rarely-changing steps first (like npm install) lets rebuilds skip work they have already done. at work.

In image builds you'll often see npm ci instead of npm install. npm ci installs exactly what's in the lockfile, skips the resolution step, and exits with an error if the lockfile is missing or out of date. That makes builds reproducible and catches dependency drift before it reaches production. The example above uses npm install for familiarity; prefer npm ci in real Dockerfiles.

Passing values in: ARG and ENV

• ARGBuild arg (ARG)A value available only while an image is being built, passed with --build-arg. It is recorded in the image history, so never use it for secrets.: a value available only while the image is being built. You set it with docker build --build-arg NODE_VERSION=20, and once the build finishes it's gone. Good for build-time choices like a version number.
• ENVENVA Dockerfile instruction that sets an environment variable available to the app at runtime. Good for configuration, not for secrets baked into the image.: an environment variableEnvironment variableA named value passed into a program from outside, read in Node as process.env. Containers use them to configure an app without changing its code. baked into the image and available to the app at runtime, the same way process.env.PORT works outside Docker. You can also override envENVA Dockerfile instruction that sets an environment variable available to the app at runtime. Good for configuration, not for secrets baked into the image. vars when starting a container with docker run -e PORT=4000.

# Build-time value: which Node base image variant to use
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine

# Runtime value: available to the app as process.env.NODE_ENV
ENV NODE_ENV=production

The distinction (build-time vs. runtime) matters more than it looks. It's the foundation of the SecretsSecretAny credential your app needs but no one else should see, like a database password or API key. Never bake one into an image. lesson later: where a value lives determines who can read it back out.

Run as a non-root user

By default, processes inside a container run as root, which amplifies the blast radius if something goes wrong. Add a USER instruction before CMD to drop privileges before the app starts. The official Node image already creates a node user for exactly this:

USER node
CMD ["node", "server.js"]

This is standard practice, not optional hardening. You'll see it checked in the exercise below.

Building and running

docker build turns the Dockerfile into an image. docker run starts a container from it.

# Build an image and tag it "my-api"
docker build -t my-api .

# Run a container, mapping host port 3000 to container port 3000
docker run -p 3000:3000 my-api

The -p host:container flag is what makes the app reachable. A container's portsPortA numbered channel a program listens on, like a phone extension for a building. A web server might listen on port 3000 so requests know where to reach it. are isolated by default. Without publishingPublish a portConnecting a port on your machine to a port inside a container with docker run -p, so traffic can reach the app. Without it, the container's ports stay isolated. one, the app is running but nothing on your machine can reach it.

Exercise