← back to books & articles
DockerDevOpsTutorial

Docker Demystified: A Beginner's Guide

January 8, 2024•12 min read

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.

  • FROM picks the starting environment instead of building one from scratch.
  • WORKDIR is cd, for every command after it.
  • COPY package*.json ./ then RUN npm install before 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.
  • CMD is 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, not localhost. Inside a Compose network, services find each other by service name. localhost inside 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 df shows the damage; docker builder prune reclaims the easy part.
  • down -v deletes your data. The -v removes 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.