Docker for beginners: what it is and how to use it in practice
What Docker is, what it's for, your first Dockerfile, the basic commands and Docker Compose: a no-fluff guide for developers who have never used containers.
The new dev just cloned the repo. Followed the README step by step. Ran it. Didn't work. Wrong Node version. Missing system library. An environment variable nobody documented. This loop has a name, "works on my machine", and it is exactly the problem Docker solves.
Docker is a tool that packages your application together with everything it needs to run (runtime, system libraries, configuration) into an image, and runs that image as a container: an isolated process that behaves the same on your laptop, your teammate's machine and the server. This guide is for people who have never used it: what it is, the first commands, your first Dockerfile, and Compose to bring up the app and the database together.
What Docker is and what it's for
When you install an application on your machine, it depends on dozens of things beyond the source code: the runtime version, operating system libraries, environment variables, configuration files. All of that exists on your computer, but not necessarily in production, or on your teammate's laptop.
Before Docker, the solution was to document everything and hope. Or use full virtual machines, which works but costs setup time and memory: a VM carries an entire operating system just to run one application.
Docker does it differently. Instead of virtualizing hardware, it isolates processes using features of the Linux kernel itself: namespaces (what the process can see: files, network, other processes) and cgroups (how much CPU and memory it can use). The result is a container, an isolated process that only sees what you defined but shares the host machine's kernel. Lighter than a VM, more predictable than installing directly on the machine.
In practice, Docker does three things in a developer's day: it standardizes the development environment (everyone runs the same version of everything), it brings up dependencies like Postgres and Redis with one command without installing anything on your machine, and it ships to production exactly the same artifact that passed CI. If you want to see where this fits in the bigger deployment and automation cycle, What DevOps Actually Is Beyond the Tools covers the culture and process behind it. And since almost every image runs Linux inside, the terminal basics from Linux for beginners are worth having.
Image, container and Docker Hub in one paragraph
An image is the immutable package: the filesystem with the application and its dependencies, plus the metadata on how to run it. A container is the image running, with a live process and its own writable layer; one image can spawn ten containers at the same time. Docker Hub is the public registry where the official images (node, postgres, python) come from. This distinction trips up every beginner and has its own post, with the full lifecycle and what happens to data when a container dies: Docker image vs container.
First Docker commands
Install Docker Desktop (Windows and Mac) or Docker Engine (Linux) from the official documentation. Then check that everything is up:
docker --version
# Docker version 29.7.2, build a7dcaa6
docker run hello-world
# Hello from Docker!
# This message shows that your installation appears to be working correctly.
docker run hello-world already does the whole cycle: it looks for the image locally, doesn't find it, pulls it from Docker Hub, creates a container, runs it and exits. The commands you'll use all week:
| Command | What it does |
|---|---|
docker images |
lists images you pulled or built |
docker ps |
lists containers running right now |
docker ps -a |
lists all of them, including stopped ones |
docker run -d --name api -p 3000:3000 my-api:1.0 |
creates and starts a container in the background |
docker logs api (or -f to follow) |
shows the process output |
docker exec -it api sh |
opens a shell inside the running container |
docker stop api |
stops the container |
docker rm api |
removes the stopped container |
docker rmi my-api:1.0 |
removes the image |
One detail that catches a lot of people: docker stop deletes nothing; the container keeps existing (it shows up in docker ps -a) until you run docker rm. If you want it gone as soon as it stops, start it with docker run --rm.
Your first Dockerfile
A Dockerfile is a text file with the instructions to build the image. An example for a Node API:
FROM node:26-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "src/index.js"]
Line by line:
FROM node:26-slimstarts from an official base image with Node 26 on top of a trimmed Debian. The version matters: Node 20 reached end of life on 2026-04-30 and no longer gets security fixes. According to the official Node.js release schedule (checked 2026-11-09), 26 has been the active LTS since 2026-10-28, supported until 2029-04-30; 24 is in maintenance until 2028-04-30 and is also a safe choice. Use an LTS version and move off it before end of life, not after.WORKDIR /appsets (and creates) the working directory inside the image.COPY package*.json ./followed byRUN npm ci --omit=devcopies only the manifest and lockfile and installs production dependencies.--omit=devis the current form; the old--only=productionstill works, but npm 11 warnsnpm warn config only Use --omit=dev.COPY . .copies the rest of the code after the dependencies, on purpose.EXPOSE 3000documents the port the process uses. It doesn't publish anything by itself.CMDis the command that runs when the container starts.
On the base image: -slim is the safe starting point. The -alpine variant is smaller, but it uses the musl libc instead of glibc, and dependencies with native binaries can break in subtle ways. Use Alpine once you've measured the gain and tested your app on it. The full comparison is in how to reduce Docker image size.
Also create a .dockerignore with node_modules, .git and .env, so COPY . . doesn't drag your local dependency folder or secrets into the image. To build and run:
docker build -t my-api:1.0 .
docker run -d --name api -p 3000:3000 my-api:1.0
curl http://localhost:3000
-p 3000:3000 maps the host port (left) to the container port (right). Without it, the process runs but is unreachable from outside. If 3000 is already taken on your machine, change only the left side: -p 8080:3000.
Why Dockerfile order matters: the layer cache
Instructions that touch the filesystem (mainly RUN, COPY and ADD) produce layers; the others, like ENV, EXPOSE and CMD, only record metadata. On the next build, Docker reuses the cache instruction by instruction until it reaches the first one that changed, and redoes everything from there down.
That's why package.json comes before the code. I ran the build above, changed one line in src/index.js and ran it again: WORKDIR, COPY package*.json and RUN npm ci came out CACHED, and only COPY . . was redone. If COPY . . came first, any code change would invalidate everything below it and npm ci would run from scratch on every build.
Docker Compose: app and database with one command
A real application has at least two services: the API and the database. Compose describes all of them in a compose.yaml file (the old docker-compose.yml name is still accepted):
services:
api:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgres://app:app@db:5432/myapp
depends_on:
db:
condition: service_healthy
db:
image: postgres:17
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: app
POSTGRES_DB: myapp
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d myapp"]
interval: 5s
timeout: 3s
retries: 5
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
docker compose up -d brings everything up; docker compose down tears it down. The API reaches the database at the hostname db, which is the service name, resolved by the internal network Compose creates.
Notice condition: service_healthy. The classic beginner trap is the short form depends_on: [db], which only guarantees startup order: Postgres is still initializing when the API tries to connect, and the API crashes. With the healthcheck, Compose waits for pg_isready to succeed before starting the API. I tested this file: db became healthy and only then did api start. There's more (hot reload, profiles, overrides) in Docker Compose for development.
pgdata is a named volume: Postgres data survives when you recreate the container. Only docker compose down -v deletes the volume along with it. Bind mounts, named volumes and tmpfs have differences that matter, covered in Docker volumes.
Why this fixes "works on my machine"
Because the environment stops being implicit. Before, it lived in stale READMEs and in the memory of whoever set up the server. With a Dockerfile, it's in the repository, versioned alongside the code. CI and production run the same image, so what passed CI is what goes live.
It doesn't eliminate every environment bug: different CPU architectures (x86 vs ARM), secrets managed outside Compose and external APIs can still diverge. But it eliminates the most common class: the wrong runtime version and a missing system dependency. When the image goes to production, the next step is hardening it (non-root user, secrets kept out of the image, vulnerability scanning), which is the subject of Dockerfile best practices.
Frequently asked questions
Does Docker replace virtual machines?
For running web apps, APIs and databases in development and deployment, in most cases yes: containers start in seconds, use less memory and are disposable. VMs still make sense when you need a different kernel or operating system, or stronger isolation than kernel sharing provides.
Does Docker work the same on Windows, Mac and Linux?
On Linux it runs natively and containers share the machine's kernel. On Mac and Windows, Docker Desktop runs a lightweight Linux VM in the background (on Windows, via WSL 2) to provide that kernel. Day to day it's transparent, with some I/O performance difference on bind mounts. In production the host is almost always Linux.
What's the difference between docker run and docker compose?
docker run starts one container at a time, with every option on the command line. docker compose reads a file describing several services, their networks, volumes and dependencies, and brings them all up together. For a one-off container, run; from two services that talk to each other onward, Compose.
Should I use Docker for local development?
If the project has a backend, a database and more than one person, yes: Compose saves hours of onboarding. For a personal script or a simple tool only you use, the payoff is smaller at first. The math flips when the project grows or another developer needs to run it.
The Dockerfile is your environment's documentation
Docker's biggest benefit isn't deployment speed: it's making the environment explicit. A well-written Dockerfile answers the questions that used to live in someone's head: which runtime version, which system dependencies, which port, which command. Start with docker run hello-world, write a Dockerfile on a -slim base with a supported LTS version, order the instructions so the cache works for you, and use Compose with a healthcheck once there's a database.
The editorial content ends here. When a compose.yaml won't start because of an indentation error, besides docker compose config (which validates and prints the resolved file), I paste the YAML into the Quick Tools YAML to JSON converter: seeing the structure as JSON makes it obvious which key ended up at the wrong level.
- 01 Does the PageSpeed Score Affect SEO? 100/100 and Failing Google doesn't rank on PageSpeed's 0 to 100 score but on Core Web Vitals from real users. Here's why a site scores 100/100 and still fails in the field.
- 02 Unit test vs integration test: the difference in practice The difference between unit and integration tests with API and database examples: what each one catches, what it costs, and when to use each in your project.