Docker: Make Local Software Repeatable

Before You Study (5 mins)

Lesson focus: Why does Netflix work on your TV, your phone, and your laptop exactly the same way? The answer is Docker. It stops the dreaded error: "But it works on MY machine!"

What you should have ready:

• Docker Desktop installed and running (download from docker.com)
• Your saved Snake Game from Lesson 01
• Antigravity open — we'll use AI assistance for the Dockerfile
• Terminal open in your project folder
• About 45 minutes of focused time

The Concept

A container is a way to package your application and the exact environment it needs to run, into a single shippable unit. You hand someone a container; they run it; it works the same on their machine as it did on yours. No "but I have a different version of Node" excuses.

People often confuse containers with virtual machines (VMs). They are not the same:

The reason a container can boot in milliseconds is that it's not booting an OS. It's just starting a process inside an isolated view of the existing kernel. Three Linux features make this possible:

• Namespaces — control what a process can see (its own PID 1, its own network interfaces, its own filesystem tree)
• cgroups — control what a process can use (CPU time, memory, disk I/O limits)
• Union filesystems — let images be built up in layers, with each layer reused across many containers

Docker is a friendly UX wrapper around these three kernel features. When you run docker run nginx, Docker asks the Linux kernel to create a new set of namespaces and cgroups, mounts a layered filesystem, and starts the nginx process inside that isolated environment.

Want the deep dive? This lesson keeps the concept short. The companion article How Docker Actually Works — Container Internals Explained walks through namespaces, cgroups, and OverlayFS with real /proc and /sys/fs/cgroup paths you can verify yourself.

The other word you'll hear constantly is image. An image is a template — a packaged filesystem snapshot, in layers, that contains your app and its dependencies. A container is a running instance of an image. One image, many containers. Like one class definition and many instances.

Layers and the build cache

The reason docker build runs fast on subsequent builds is the layer cache. Each instruction in a Dockerfile produces one layer:

FROM node:20-alpine                  # layer 1: base image (~50MB)
WORKDIR /app                         # layer 2: filesystem change
COPY package*.json ./                # layer 3: dependency manifests
RUN npm ci --production              # layer 4: installed node_modules
COPY . .                             # layer 5: your source code
EXPOSE 3000                          # layer 6: metadata only
CMD ["node", "server.js"]            # layer 7: default command

Docker caches each layer by content. The next time you build, if package.json hasn't changed, layers 1-4 reuse the cache and only layer 5 (your code) rebuilds. A clean rebuild that would take 90 seconds drops to 5. The Dockerfile instruction order matters — putting COPY . . before npm ci would invalidate the cache on every code change. Always copy dependency manifests, install, and only then copy source.

This is the single biggest practical lesson hiding inside "Docker": the build cache is your friend if you order instructions from least-frequently-changing to most-frequently-changing.

Why containers won

Before Docker (2013), shipping software meant either:

• "Here is a tar.gz. Good luck installing 47 dependencies in the right order."
• "Here is a 4GB virtual machine image. Allocate 8GB of RAM and pray your laptop survives."

Containers replaced both. A 50MB image starts in milliseconds, runs anywhere with a Linux kernel (Mac, Windows via WSL, every cloud), and packages exactly what your app needs. Netflix, Spotify, Stripe, every company that ships software at scale today runs on containers. The pattern is universal because the problem it solves — "will my code run somewhere other than my laptop" — is universal.

Quick Concepts

What We Will Build

By the end of this lesson, you will have done these specific things:

1. Verified Docker Desktop is running by typing docker --version in the terminal.
2. Opened your Snake Game project folder.
3. Asked Antigravity to write a Dockerfile for a simple Node.js or static-HTML project, and inspected it line by line.
4. Built the image with docker build -t snake-game . (note the trailing dot).
5. Run the container with docker run -p 3000:3000 snake-game.
6. Loaded http://localhost:3000 in your browser and confirmed your game runs inside the container.
7. Stopped the container and inspected the image with docker images and docker history.

When you finish, you will have shipped your first container. Not metaphorically — actually.

Common Pitfalls

These are the four mistakes most people make in their first Docker build, in roughly the order they hit:

1. "Port already in use" — you ran the container, then ran it again without stopping the first. Both want port 3000. Fix: docker ps to see what's running, docker stop <id> to stop it. Or use a different host port: docker run -p 3001:3000 snake-game.
2. "My changes aren't showing up" — you edited a source file but the container is still serving the old code. The image was built from the old code; the container runs that frozen image. Fix: rebuild (docker build -t snake-game .) or use a volume mount in development (-v $(pwd):/app). The first is correct for shipping; the second is correct for iterating.
3. Image is 1.5GB — you used node:20 (full Debian) instead of node:20-alpine (small Linux variant). Or you COPY . before .dockerignore was set up, so node_modules and .git got baked in. Fix: prefer slim/alpine base images, write a .dockerignore that excludes node_modules, .git, .env, and other local-only files.
4. "docker: command not found" — Docker Desktop isn't running on your Mac/Windows machine. The docker CLI talks to the Docker daemon; if the daemon isn't running, the CLI returns this error. Fix: open Docker Desktop and wait for the whale icon to settle.

If you hit a pitfall not on this list, the fix is almost always in docker logs <container-id> — the container's stdout/stderr is the first place to look.

Think About

Before studying, consider:

1. Have you ever sent a file to a friend and they couldn't open it because they "didn't have the right font"? Now imagine your whole app is the file, and the font is Node version 20.11 with these 47 npm packages and this exact Linux distribution. That's the problem Docker solves.
2. If a container only takes milliseconds to start, what could you do with that speed that you couldn't do with virtual machines? (Hint: think about how Netflix handles a sudden traffic spike.)
3. Why does the order of instructions in a Dockerfile matter? What would go wrong if you put COPY . . before RUN npm ci?

By the End

After this lesson, you'll:

• ✅ Understand what containers actually are at the kernel level
• ✅ Have written your first Dockerfile (with AI assistance, but you'll read every line)
• ✅ Have built your first image and run your first container
• ✅ Be able to explain the difference between an image and a container
• ✅ Know where to read more when you want to go deeper (the companion blog post)

Let's package your app. 📦

What We Learned

• Containers are not VMs. They share the host kernel and use Linux namespaces, cgroups, and union filesystems for isolation.
• An image is a template; a container is a running instance. One image can spawn thousands of containers.
• A Dockerfile is the recipe. Each instruction creates a new layer; layers are reused across builds and across images.
• Layers cache aggressively. If you don't change a layer, Docker doesn't rebuild it — which is why ordering instructions in your Dockerfile matters.
• Port mapping (-p host:container) is how the outside world reaches a service running inside a container.
• Containers are ephemeral by default. Anything you write inside a running container is lost when it stops, unless you mount a volume.

Commands We Used

# Verify Docker is running
docker --version
docker info

# Build an image from the current directory's Dockerfile
docker build -t snake-game .

# Run the container, mapping host port 3000 to container port 3000
docker run -p 3000:3000 snake-game

# Run in the background (detached) and give it a name
docker run -d --name snake -p 3000:3000 snake-game

# See running containers
docker ps

# See ALL containers (including stopped)
docker ps -a

# Stop and remove a container
docker stop snake
docker rm snake

# See all local images
docker images

# Inspect the layers of an image
docker history snake-game

# Clean up unused images, containers, networks
docker system prune

A minimal Dockerfile for a Node.js project looks like this:

# Use the official Node 20 image as the base
FROM node:20-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy package files first — this layer caches across builds
COPY package*.json ./
RUN npm ci --only=production

# Copy the rest of the source code
COPY . .

# Tell Docker the container will listen on port 3000
EXPOSE 3000

# The command that runs when the container starts
CMD ["node", "server.js"]

Why It Matters

Docker is one of the technologies that genuinely changed how the internet is built. Before containers, deploying a new version of a web app meant SSH-ing into a server, hoping its configuration matched your local machine, and praying nothing broke. After containers, deployment is "build the image, push it, run it."

This is why Netflix can serve the same experience on every device, why your bank can scale up during salary day without buying new hardware, and why a solo developer can ship a side project to thousands of users from a laptop. Containers compress the gap between "code on my machine" and "code in production" from hours to seconds.

The lesson glossed over a few things you'll hit when projects grow:

• Multi-stage builds — to keep production images small by discarding build tools after compilation. Worth learning when your image grows past 200 MB.
• Docker Compose — to orchestrate multiple containers (frontend, API, database) with one file. We touch this in Lesson 07, but the Docker Compose Explained article goes deeper.
• Volumes for persistence — for databases and stateful services. The container is ephemeral; the volume is not.
• Container security — containers share the host kernel, so a kernel exploit can escape. For untrusted code at scale, microVMs (Firecracker, the technology behind AWS Lambda) are still safer.

Want to understand exactly how a container achieves isolation, with real verifiable commands? Read How Docker Actually Works — Container Internals Explained — it walks through namespaces and cgroups with /proc and /sys/fs/cgroup paths you can inspect on your own machine right after this lesson.

Checklist

• I ran docker --version and saw a version number
• I wrote a Dockerfile and read every line
• I built an image with docker build
• I ran a container with docker run -p
• I loaded my game in a browser at localhost:3000
• I ran docker history on my image and saw the layers
• I stopped and removed the container cleanly

Quick Quiz

Q1: What do containers and virtual machines NOT share?

• A) Disk space
• B) The kernel — VMs run their own, containers share the host's ✓
• C) The internet connection

Q2: What does the -p 3000:3000 flag do in docker run?

• A) Runs the container as a "production" build
• B) Maps host port 3000 to container port 3000 ✓
• C) Pauses the container after 3000 milliseconds

Q3: Why is the order of instructions in a Dockerfile important?

• A) Docker reads it backwards
• B) Each instruction creates a layer; later layers invalidate earlier caches if changed ✓
• C) The compiler refuses to run otherwise

Q4: What happens to data written inside a running container by default?

• A) It is automatically saved to your home folder
• B) It is lost when the container stops, unless you mount a volume ✓
• C) It is encrypted and stored on Docker Hub

Bonus Challenge

Modify your Dockerfile to use a multi-stage build: one stage for installing dependencies and building, a second stage that copies only the built output and runs it. Compare image sizes with docker images before and after. You should see a meaningful reduction.

Next Lesson

Lesson 07: FREE Hosting Forever — Cloudflare Tunnel

You'll learn: Your container runs on localhost:3000 — but localhost only exists on your machine. Tomorrow's lesson is how to share your running container with anyone in the world, for free, without buying hosting.

You shipped your first container. The world just got a little smaller. 📦