"It works on my machine"
A program is never just its own code. It needs a particular version of the language, particular libraries, some system tools, a few settings and files in the right places.
Your laptop has all of that, built up over months. The server does not. So the program runs for you and fails there, and finding the one difference can take a day.
The idea behind containers: stop shipping the program alone. Ship it together with everything it needs.
Two words do most of the work.
- An image is the package: your program plus its files, libraries and settings, frozen. It does not change.
- A container is a running copy of an image.
The relation is like a recipe and a meal, or a class and an object. One image can be started as many containers as you like, on any machine, and each one starts out identical.
A container is not a small virtual machine
This is the most common misunderstanding. A virtual machine pretends to be a whole computer and boots its own operating system. A container does nothing of the kind.
node server.js
- sees all 214 processes
- sees the whole disk
- shares the machine's ports
Start. An ordinary program running on a server. It can see every other process, every file on the disk and every network port. If it needs Node 22 and another program needs Node 18, they are in each other's way.
- Running
- 1 process
- Kernels running
- 1
A container is an ordinary process. The operating system's kernel does two things to it:
- Namespaces give it a private view. It sees only its own processes, its own files (the ones from the image) and its own network ports.
- Cgroups limit what it may use: this much memory, this much CPU.
Nothing boots, so a container starts about as fast as any program. See Processes and Threads.
| Container | Virtual machine | |
|---|---|---|
| What it is | A process with a private view | A pretend computer |
| Kernel | Shares the host's | Has its own |
| Starts in | Well under a second | Many seconds |
| Size | Often tens of megabytes | Often gigabytes |
| Isolation | Good | Stronger |
| How many fit on one server | Hundreds | Tens |
How an image is built
An image is described by a text file called a Dockerfile. It is a list of instructions, run from top to bottom.
FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]| Instruction | Meaning |
|---|---|
FROM | Start from an existing image. Here, a small Linux with Node 22 already installed. |
WORKDIR | Work in this folder from now on. |
COPY | Copy files from your project into the image. |
RUN | Run a command while building, and keep the files it produces. |
CMD | The command to start when a container is run. |
Each instruction saves its changes as a layer. An image is a stack of layers, one on top of another.
Layers and the build cache
Layers are what make builds fast, or slow.
When you build again, Docker goes through the instructions in order. If an instruction and its inputs are the same as last time, it reuses the saved layer and skips the work. But as soon as one layer has to be rebuilt, every layer after it is rebuilt too, because each one sits on top of the one before.
Watch what that means for the Dockerfile above when one line of code changes.
Dockerfile
1FROM node:22-slim2WORKDIR /app3COPY . .4RUN npm install5CMD ["node", "server.js"]
Image layers, first build
Start. A Dockerfile is a recipe. Each instruction runs in order, and the files it changes are saved as one layer.
- First build
- 0 s
- Build after a one-line change
- –
COPY . . copies all the code, so any change to any file makes that layer new. The package install comes after it, so it runs again, although the list of packages is exactly the same.
The fix is only a change of order. Copy the package list first, install, and copy the rest of the code last.
FROM node:22-slim
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
CMD ["node", "server.js"]Dockerfile
1FROM node:22-slim2WORKDIR /app3COPY package.json .4RUN npm install5COPY . .6CMD ["node", "server.js"]
Image layers, first build
Start. A Dockerfile is a recipe. Each instruction runs in order, and the files it changes are saved as one layer.
- First build
- 0 s
- Build after a one-line change
- –
In this model the rebuild goes from 41 seconds to 1. The rule to remember: put what changes rarely near the top, and what changes often near the bottom.
Dockerfile
1FROM node:22-slim2WORKDIR /app3COPY . .4RUN npm install5CMD ["node", "server.js"]
Image layers, first build
Start. A Dockerfile is a recipe. Each instruction runs in order, and the files it changes are saved as one layer.
- First build
- 0 s
- Build after a one-line change
- –
Layers are also shared. If ten of your images start FROM node:22-slim, that base is downloaded and stored once, not ten times.
Running it
docker build -t my-app . # build an image from the Dockerfile here
docker run -p 8080:3000 my-app # start a container from it-p 8080:3000 connects port 8080 on your machine to port 3000 inside the container. Without it, the container's ports are private and nothing outside can reach them.
Good habits
Start from a small base image
Images with
slimoralpinein the name leave out tools you do not need. Smaller images download faster and have fewer things that can have security holes.Name exact versions
node:22-slim, notnode:latest. Otherwise the same Dockerfile builds a different image next month.Add a .dockerignore file
Keep
node_modules,.gitand local secrets out ofCOPY . ..Never put secrets in an image
Anyone who has the image can read every layer, including files that a later instruction deleted. Pass passwords and keys in when the container starts.
One main process per container
The web server in one container, the database in another. Each can then be restarted, replaced and scaled by itself.
Where this leads
Running one container by hand is easy. Running hundreds across many servers, restarting the ones that crash and sharing traffic between them, is the job of an orchestrator such as Kubernetes. Containers are the unit it works with. See Load Balancing and Monolith or Microservices.
Key takeaways
- An image packages a program with everything it needs. A container is a running copy of an image.
- A container is an ordinary process that the kernel gives a private view and a resource limit. It is not a virtual machine.
- Each Dockerfile instruction makes a layer, and an unchanged layer is reused from the cache.
- When one layer changes, every layer after it is rebuilt, so copy the code as late as possible.
- Files written inside a container vanish with it. Data that must last goes in a volume.