Every developer has said it at some point: "it works on my machine." Someone else pulls your code, and something about their Java version, their OS, or a missing environment variable breaks it. Docker exists to make that excuse obsolete by packaging an application together with everything it needs — the runtime, libraries, configuration — into one portable unit called a container.

Containers vs virtual machines

A virtual machine emulates an entire computer, including its own full operating system kernel, which makes it heavy — often gigabytes in size and slow to start. A container shares the host machine's kernel and only packages the application and its dependencies, which makes containers dramatically lighter and faster to start, typically in under a second.

• Virtual machine: full OS per app, strong isolation, heavy, slow to boot.
• Container: shared host kernel, process-level isolation, lightweight, starts almost instantly.

The core vocabulary

• Image — a read-only blueprint: your application code plus everything needed to run it. Think of it as a snapshot or a class.
• Container — a running instance of an image. Think of it as an object created from that class. You can run many containers from one image.
• Dockerfile — a text file with step-by-step instructions for building an image.
• Registry — a place to store and share images, such as Docker Hub.

A tiny taste of the workflow

docker build -t my-app .
docker run -p 8080:8080 my-app

The first command reads a Dockerfile in the current directory and builds an image tagged my-app. The second starts a container from that image, mapping port 8080 inside the container to port 8080 on your machine so you can open it in a browser. That is genuinely most of what you will type day to day once a Dockerfile exists.

Why teams actually adopt it

• Consistency — the exact same image runs on a laptop, a CI pipeline, and production.
• Isolation — an app's dependencies never collide with another app's dependencies on the same machine.
• Portability — the same image runs on any machine with Docker installed, regardless of the underlying OS.
• Easy scaling — spinning up ten identical containers behind a load balancer is trivial once the image exists.

What is next

The rest of this series is hands-on: writing your first Dockerfile, learning the handful of commands you will use daily, wiring multiple containers together with Docker Compose, and finally two real projects — dockerizing a Node.js API, and a genuine multi-stage Dockerfile for a Spring Boot app, the same pattern used to containerize this very site.

A Dockerfile is just a plain text file, usually named exactly Dockerfile with no extension, sitting in the root of your project. Each line is an instruction that adds a layer to the image being built. Let us build one for a small Node.js app, since it shows every important instruction without much noise.

The project it packages

// server.js
const http = require("http");
http.createServer((req, res) => {
  res.end("Hello from inside a container!");
}).listen(3000);

The Dockerfile, instruction by instruction

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .

EXPOSE 3000
CMD ["node", "server.js"]

What each line actually does

• FROM node:20-alpine — starts from an existing image that already has Node.js 20 installed, built on the tiny alpine Linux distribution. You almost never build an image completely from scratch; you build on top of a trusted base image.
• WORKDIR /app — sets the working directory inside the image. Every instruction after this runs relative to /app, and it is created automatically if it does not exist.
• COPY package*.json ./ — copies only the package files first, before the rest of the source code.
• RUN npm install --production — installs dependencies inside the image at build time.
• COPY . . — copies the rest of the project source into the image.
• EXPOSE 3000 — documents which port the app listens on. It does not actually publish the port by itself; that happens with -p when you run the container.
• CMD ["node", "server.js"] — the command that runs when a container starts from this image. A Dockerfile can only have one CMD; if you list several, only the last one takes effect.

Why COPY package*.json happens before COPY . .

This ordering is not an accident, and it is one of the most important habits in writing Dockerfiles. Docker caches each layer, and reuses a cached layer if the instruction and its inputs have not changed. Dependencies change far less often than application source code, so copying the package files and running npm install first means Docker can reuse that entire cached layer on almost every rebuild, only re-running the slow install step when dependencies actually change. Copy everything at once instead, and Docker invalidates the dependency-install layer on every single source code change — turning a two-second rebuild into a two-minute one.

Building and running it

docker build -t hello-node .
docker run -p 3000:3000 hello-node

Visiting http://localhost:3000 now hits the server running inside the container. The -t hello-node flag tags the image with a friendly name so you do not have to reference it by its long generated hash.

One more essential file: .dockerignore

node_modules
.git
*.log

Just like .gitignore, a .dockerignore file stops unwanted files from being copied into the image during a COPY . . step — keeping images smaller and builds faster, and avoiding accidentally shipping your local node_modules or .git history into a production image.

Docker has a large command surface, but in practice a working developer reaches for the same dozen or so commands constantly. This tutorial is a practical tour of exactly those.

Running containers

docker run -p 8080:8080 my-app          # run in the foreground
docker run -d -p 8080:8080 my-app       # -d = detached, runs in the background
docker run --name my-container my-app   # give it a memorable name

Seeing what is running

docker ps            # running containers
docker ps -a         # every container, including stopped ones

docker ps is usually the very first command you run when something seems off — is the container even up, and what port did it actually bind to?

Looking inside a running container

docker logs my-container          # see its console output
docker logs -f my-container       # follow the logs live, like tail -f
docker exec -it my-container sh   # open an interactive shell inside it

docker exec -it ... sh (or bash, if the image has it) is enormously useful for debugging — you drop into a real shell running inside the exact same filesystem and environment as your app, and can poke around, check environment variables, or verify a file actually made it into the image.

Stopping and cleaning up

docker stop my-container
docker rm my-container
docker rmi my-app

stop gracefully shuts a container down, rm deletes a stopped container, and rmi deletes an image entirely. It is common early on to accumulate a pile of stopped containers and unused images; docker system prune clears out the unused ones in one go, which is worth knowing once your disk usage starts climbing.

Persisting data with volumes

A container's filesystem is disposable — delete the container and everything written inside it is gone. For data that needs to survive (a database's files, uploaded content), mount a volume:

docker run -v my-data:/var/lib/postgresql/data postgres

This tells Docker "store this container path on a named, persistent volume managed by Docker," so the data survives even if the container is removed and recreated. You can also mount a folder from your own machine directly, which is handy for local development so code edits on your laptop show up instantly inside the running container:

docker run -v $(pwd):/app -p 3000:3000 hello-node

Environment variables

docker run -e DATABASE_URL=postgres://... -e NODE_ENV=production my-app

Passing configuration as environment variables rather than baking it into the image is standard practice — it means the exact same image can run in development, staging and production, just configured differently at startup.

A quick mental checklist

• Is it running? docker ps
• What is it printing? docker logs -f
• Need to poke around inside? docker exec -it ... sh
• Need data to survive a restart? mount a volume with -v

Those handful of commands cover the overwhelming majority of day-to-day Docker work. Next: Docker Compose, for when one container is no longer enough.

A real application is rarely just one container. A typical setup might need a backend API, a database, and maybe a cache — each running in its own container, but needing to talk to each other. Running each one by hand with long docker run commands gets old fast, and remembering the right flags every time is error-prone. Docker Compose solves this with a single YAML file describing every service an app needs.

A backend plus a database

version: "3.9"
services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://appuser:secret@db:5432/appdb
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=appdb
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Reading the file

• services — each key under here (app, db) becomes its own container.
• build: . — for the app service, build an image from the Dockerfile in the current directory, rather than pulling a pre-built one.
• image: postgres:16 — for the db service, just pull this exact, ready-made image from Docker Hub instead of building one.
• depends_on — starts db before app. Note this only controls start order, not whether Postgres has finished initializing — a well-written app should retry its database connection on startup rather than assume it is instantly ready.
• volumes — the named volume db-data keeps the database's files on disk even if the container is recreated.

The magic of service names as hostnames

Notice the database URL uses db as the hostname, not localhost. Compose creates a private network for the whole file, and every service can reach every other service by its service name, exactly as if it were a real DNS hostname. This is one of the most useful things Compose gives you for free.

Running it

docker compose up            # build/pull and start everything, logs in the foreground
docker compose up -d         # same, but detached in the background
docker compose logs -f app   # follow just the app service's logs
docker compose down          # stop and remove all the containers
docker compose down -v       # also remove the named volumes (careful — deletes data)

One command spins the entire stack up in the right order with the right network wired together, which is a huge improvement over juggling several long docker run commands by hand.

When you would reach for this

• Local development, so every teammate runs the exact same backend-plus-database setup with one command.
• CI pipelines, spinning up a real database for integration tests.
• Small, single-machine deployments where a full orchestrator like Kubernetes would be overkill.

With the fundamentals and Compose in place, the last two tutorials build two genuinely real Dockerfiles: one for a Node.js API, and one for a Spring Boot app using the exact multi-stage pattern this very site is deployed with.

This tutorial takes an actual small Express API and containerizes it properly — not just a "hello world" Dockerfile, but the kind of setup you would genuinely deploy.

1. The project being containerized

// package.json
{
  "name": "notes-api",
  "version": "1.0.0",
  "scripts": { "start": "node index.js" },
  "dependencies": { "express": "^4.19.2" }
}

// index.js
const express = require("express");
const app = express();
app.use(express.json());

let notes = [{ id: 1, text: "Buy milk" }];

app.get("/notes", (req, res) => res.json(notes));
app.post("/notes", (req, res) => {
  const note = { id: Date.now(), text: req.body.text };
  notes.push(note);
  res.status(201).json(note);
});
app.get("/health", (req, res) => res.send("ok"));

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on ${port}`));

2. The Dockerfile

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

ENV NODE_ENV=production
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s 
  CMD wget -qO- http://localhost:3000/health || exit 1

CMD ["node", "index.js"]

Choices worth explaining

• npm ci instead of npm install — ci installs exact versions straight from package-lock.json and fails if the lockfile and package.json disagree, which is exactly the strict, reproducible behaviour you want for a build that might run on a CI server or a teammate's machine.
• --omit=dev — skips devDependencies like test runners and linters, since none of that is needed to actually run the app in production, keeping the image smaller.
• ENV NODE_ENV=production — many libraries, Express included, change their behaviour (better performance, less verbose errors) when this is set.
• HEALTHCHECK — tells Docker how to actively check whether the app inside the container is actually healthy, not just "running." Orchestrators like Docker Swarm or a load balancer can use this to stop sending traffic to a container that is up but not responding correctly.

3. A .dockerignore that actually matters here

node_modules
npm-debug.log
.git
.env
*.md

Excluding node_modules matters twice over: it keeps the build context small and fast to send to the Docker daemon, and it guarantees the dependencies actually installed are the ones npm ci installs fresh inside the image for the correct Linux/alpine platform, not whatever happens to be sitting in your local folder from your own OS.

4. Passing real configuration in

docker build -t notes-api .
docker run -d -p 3000:3000 -e PORT=3000 --name notes notes-api

The app already reads process.env.PORT, so the exact same image can be told to listen on a different port in different environments without touching a single line of code — this is the same reason the Dockerfile in this very project reads PORT from the environment for Spring Boot, a pattern common to virtually every container platform (Cloud Run, Heroku, Render and friends all inject a PORT variable at runtime).

5. Verifying it for real

curl http://localhost:3000/health
curl http://localhost:3000/notes
curl -X POST http://localhost:3000/notes -H "Content-Type: application/json" -d "{"text":"Walk the dog"}"

This is a genuinely production-shaped Dockerfile: a locked dependency install, a smaller image via --omit=dev, externalized configuration, and a real health check — not just something that happens to boot on your own laptop.

The last project uses a genuinely real example: the multi-stage Dockerfile pattern used to build and ship this very Spring Boot site. It solves a problem the earlier Node example did not have to deal with — compiling the app is itself a heavyweight step that needs its own toolchain.

The problem with a single-stage build

A Spring Boot app needs Maven and a full JDK to compile, but running the finished app only needs a much smaller JRE. Installing Maven and a JDK into your final runtime image bloats it with build tools nobody needs once the jar exists, and it means every build tool ever gets shipped to production. A multi-stage build fixes this by using one temporary image to compile the app, then copying just the finished artifact into a second, much leaner image.

Stage 1: build

FROM maven:3.9.9-eclipse-temurin-17 AS build
WORKDIR /app

COPY pom.xml .
RUN mvn -q -B dependency:go-offline

COPY src ./src
RUN mvn -q -B -DskipTests package

AS build names this stage so it can be referenced later. Just like the Node example, dependencies are resolved in their own step, using dependency:go-offline to download every Maven dependency, before the actual source code is copied in — so an ordinary code change reuses the cached dependency layer instead of re-downloading the internet on every build. -DskipTests skips running the test suite during the image build itself; tests belong in CI, run once, not repeated on every single Docker build.

Stage 2: runtime

FROM eclipse-temurin:17-jre-jammy
WORKDIR /app

RUN addgroup --system app && adduser --system --ingroup app app
COPY --from=build /app/target/*.jar app.jar
RUN chown app:app app.jar
USER app

EXPOSE 8080
ENV JAVA_OPTS=""

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

This second FROM starts a completely fresh image based only on a JRE (no Maven, no JDK, no source code) — eclipse-temurin:17-jre-jammy instead of the much larger maven:... image from stage 1. COPY --from=build /app/target/*.jar app.jar is the key line: it reaches back into the first stage and pulls out only the compiled jar file, leaving every build tool and every intermediate file behind.

Running as a non-root user

The addgroup / adduser / USER app sequence creates an unprivileged system user and switches to it before the app runs. Containers run as root by default unless told otherwise, and if an attacker ever found a way to execute code inside the container, running as root would hand them far more power over that container than they need. This is a small addition with a real security payoff, and it is standard practice for any production image.

Reading configuration from the environment

# application.yml
server:
  port: ${PORT:8080}

Because the port is read from an environment variable with a sensible default, the exact same image can be deployed to a platform like Google Cloud Run, which injects its own PORT value at startup, without changing a single line of application code or the Dockerfile itself.

Building and running the whole thing

docker build -t my-spring-app .
docker run -p 8080:8080 my-spring-app

Docker automatically runs both stages in order and discards everything from the build stage except what was explicitly copied out with --from=build — the final image contains only a JRE, a non-root user, and one jar file.

Why this exact pattern is worth remembering

• Smaller final image — no build tools, no source code, no intermediate Maven cache shipped to production.
• Faster, cached rebuilds — dependencies download once and are reused across builds until pom.xml actually changes.
• Better security — a non-root user with the smallest possible attack surface.
• Environment-driven configuration — one image, deployable anywhere, configured entirely at runtime.

This two-stage shape — a heavy build stage, a lean runtime stage, only the compiled artifact copied across — is the pattern to reach for with any compiled language: Java, Go, .NET or C++ all benefit from exactly this same structure.