Docker looks intimidating from the outside - a new CLI, a new file format, a daemon doing something in the background. It gets simple the moment you have the right mental model for four words.
The problem it solves
You build something. It runs. You send it to a friend, and it doesn't.
Different Python version. A system library you installed months ago and forgot. An environment variable that only exists on your machine. The bug isn't in your code - it's in the *gap between two computers*.
Docker closes that gap by shipping the environment along with the code.
The four words
Image
An image is a recipe. It describes exactly what goes into your environment - base OS, language runtime, dependencies, your code - but nothing is running yet.
Container
A container is a cake baked from that recipe. A running instance of the image. You can bake ten cakes from one recipe, and throwing one away doesn't harm the recipe.
Volume
Containers are disposable, and that's a problem for databases. A volume is storage that lives outside the container's lifecycle - so you can delete and recreate the container and your data is still there.
Compose
Real apps aren't one container. They're a frontend, a backend, a database, a cache. Compose is the head chef: one file describing every service, one command to start them all.
Your first Dockerfile
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]Read it top to bottom - it's just a setup script with an important trick in the middle.
FROMpicks the starting environment instead of building one from scratch.WORKDIRiscd, for every command after it.COPY package*.json ./thenRUN npm installbefore copying the rest of the code is deliberate. Each line is a cached layer, and layers rebuild only when their inputs change. Copy your source first and every one-character edit reinstalls all your dependencies.CMDis what runs when the container starts.
Multiple services with Compose
services:
web:
build: ./services/web
ports:
- "3000:3000"
api:
build: ./services/api
environment:
DATABASE_URL: postgresql://postgres:postgres@postgres:5432/app
postgres:
image: postgres:15-alpine
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:Two details in there are worth more than the rest of the file:
"3000:3000"is host port : container port. The left number is the door on your machine; the right one is the door inside. When the left port is already taken by something else, change the left number only.- The database host in that URL is
postgres, notlocalhost. Inside a Compose network, services find each other by service name.localhostinside a container means *that container* - one of the most common beginner bugs lives right here.
The five commands you'll actually use
docker compose up -d --build # build and start everything, detached
docker compose ps # what's running, and on which ports
docker compose logs -f api # follow one service's logs
docker compose exec api bash # get a shell inside a running container
docker compose down # stop everything (add -v to delete volumes too)Things that will bite you
- "Port is already allocated." Something else on your machine owns that port. Change the host side of the mapping.
- "No space left on device." Images and build cache accumulate quietly.
docker system dfshows the damage;docker builder prunereclaims the easy part. down -vdeletes your data. The-vremoves volumes. That's the fresh-start button, and it is not undoable.- Code changes not showing up. In production images your code was copied in at build time. Either rebuild, or mount it as a volume for development.
When it clicks
The moment Docker stops being annoying is the moment you delete every container you own, run one command, and watch your whole stack come back exactly as it was.
That's the payoff: deployment becomes boring.