Docker for Students Who Don't Understand Docker

Docker is one of those tools that every job posting mentions, every tutorial assumes you know, and nobody actually explains properly. You have probably heard things like "it is like a lightweight virtual machine" or "it packages your app in a container." Both of those descriptions are either wrong or so vague they are useless.

This guide will explain Docker from scratch. Not the marketing version. The real version — what it actually does at the operating system level, how to write a Dockerfile you actually understand, how to run multiple services together, and the mistakes that will waste hours of your time if nobody warns you about them. By the end, you will know when Docker is the right tool and when it is overkill.

1. What Docker Actually Is (And Isn't)

Docker Is Not a Virtual Machine

This is the single most important thing to understand, and most tutorials get it wrong. A virtual machine (VM) emulates an entire computer. It runs its own operating system kernel, its own memory management, its own device drivers. When you start a VM, you are booting a complete operating system inside your existing operating system. That is why VMs are heavy — they need gigabytes of RAM and take minutes to start.

Docker containers are fundamentally different. A container is just a regular process running on your host machine, but with isolation. It shares your host's kernel. It does not boot a new operating system. It does not emulate hardware. It uses Linux kernel features called namespaces (which isolate what the process can see) and cgroups (which limit how much CPU and memory the process can use) to create the illusion that the process is running in its own little world.

Think of it this way: a VM is like renting an entire apartment. You get your own kitchen, bathroom, electricity meter — everything. A container is like renting a room in a shared house. You get your own locked room (isolation), but you share the kitchen, plumbing, and electricity (the kernel). That is why containers start in milliseconds, not minutes. That is why they use megabytes of RAM, not gigabytes.

Why Docker Matters: The "Works on My Machine" Problem

You have probably experienced this. You build a project on your laptop. It runs perfectly. You send it to a classmate, a professor, or deploy it to a server, and it breaks. The Python version is different. A system library is missing. An environment variable is not set. The file paths use backslashes instead of forward slashes.

Docker solves this by packaging your application along with its entire environment — the operating system libraries, the language runtime, the dependencies, the configuration. When you build a Docker image, you are creating a snapshot that contains everything your application needs to run. Anyone with Docker installed can run that image and get the exact same behavior, regardless of whether they are on macOS, Windows, or Linux.

This is not just convenient. It is transformative for professional software development:

• Consistent environments: Your development, testing, and production environments are identical. No more "it worked in dev but broke in prod."
• Easy onboarding: A new team member clones the repo, runs docker compose up, and has the entire application running in minutes — database, cache, backend, everything.
• Microservices: You can run your API in one container, your database in another, and your cache in a third. Each can be built, deployed, and scaled independently.
• Reproducible deployments: The image you tested is the exact image you deploy. There is no drift between what you tested and what runs in production.

2. Your First Dockerfile Explained Line by Line

A Dockerfile is a text file that tells Docker how to build an image. Every line is an instruction, and every instruction creates a layer. Layers are cached, which means if you change line 7 of your Dockerfile, Docker only rebuilds from line 7 onward — everything before it uses the cache. This matters for build speed, and we will come back to it.

Python Example

Here is a complete Dockerfile for a Python Flask application, with every line explained:

Let us break down what each instruction does:

• FROM python:3.12-alpine — Every Dockerfile starts with FROM. It specifies the base image to build on top of. Here we are using the official Python 3.12 image built on Alpine Linux. Alpine is tiny (about 5MB) compared to the default Debian-based images (around 120MB). Always pin your version. FROM python without a version tag will pull whatever "latest" is today, which might be a different version tomorrow and break your build.
• WORKDIR /app — Sets the working directory for all commands that follow. If /app does not exist, Docker creates it. This is like doing mkdir /app && cd /app but cleaner.
• COPY requirements.txt . — Copies your requirements.txt from your local machine into the container's /app directory. We copy this file separately from the rest of our code for a specific reason: layer caching. If your requirements have not changed, Docker reuses the cached layer and skips the pip install step entirely. This saves minutes on every build.
• RUN pip install --no-cache-dir -r requirements.txt — Executes a command during the build. RUN creates a new layer. The --no-cache-dir flag tells pip not to store downloaded packages, keeping the image smaller.
• COPY . . — Copies everything from your project directory into the container. This comes after the dependency installation so that changing your code does not invalidate the dependency cache.
• EXPOSE 5000 — This is documentation only. It tells anyone reading the Dockerfile that the app listens on port 5000. It does not actually open the port. You still need -p 5000:5000 when you run the container.
• CMD ["python", "app.py"] — Defines the default command that runs when a container starts from this image. Use the JSON array format (exec form), not a string. The string form wraps your command in a shell, which causes issues with signal handling.

Node.js Example

Here is the equivalent for a Node.js Express application:

The pattern is identical: base image, working directory, dependencies first (for caching), then application code, then the run command. Notice npm ci instead of npm install. The ci command installs from the lockfile exactly, which is faster and more deterministic — exactly what you want in a container build.

The .dockerignore File

When Docker builds an image, it sends your entire project directory to the Docker daemon as the "build context." If you do not have a .dockerignore file, that means it sends everything — node_modules (which can be hundreds of megabytes), your .git directory (your entire commit history), .env files (your secrets), and any other junk sitting in your project folder.

Create a .dockerignore file in your project root:

Without a .dockerignore, a typical Node.js project sends 200–500MB of build context to the daemon. With it, you send maybe 5–10MB. Your builds go from 30 seconds to 3 seconds. This is not optional — it is a requirement for any sane Docker workflow.

3. Multi-Stage Builds: Shrink Your Images by 90%

Here is a problem you will run into quickly. You have a React frontend that needs Node.js and hundreds of megabytes of dev dependencies to build. But once it is built, the output is just a folder of static HTML, CSS, and JavaScript files. You do not need Node.js to serve those files. You do not need node_modules. You do not need webpack or TypeScript or any build tools.

Without multi-stage builds, your image contains all of that build tooling — and you end up shipping a 1.2GB image that only needs 50MB of actual content. Multi-stage builds solve this by letting you use multiple FROM statements in a single Dockerfile. Each FROM starts a new "stage." You can copy files from one stage to another, leaving behind everything you do not need.

Practical Example: React Application

Let us walk through what happens:

• Stage 1 (build): We start from a Node.js image, install all dependencies (including dev dependencies like webpack, TypeScript, and testing libraries), copy our source code, and run the build command. This generates the /app/dist folder with optimized static files.
• Stage 2 (production): We start fresh from a tiny nginx:alpine image (about 40MB). We use COPY --from=build to grab only the built files from Stage 1. The final image has nginx and your static files. Nothing else.

Real Size Comparison

Here is what this looks like in practice with a standard React application:

• Without multi-stage: ~1.2GB (Node.js runtime + node_modules + build tools + source code + built files)
• With multi-stage: ~150MB (nginx + built static files only)
• Reduction: 87.5%

That is not a small difference. It means faster deployments, less bandwidth, less storage cost, and faster container startup times. In a CI/CD pipeline where you build and push images dozens of times a day, this adds up fast.

Multi-Stage for a Go Application

Go is the best example of multi-stage power because Go compiles to a single static binary. You can use a build stage with the full Go toolchain, then copy just the binary into a scratch image (which is literally an empty filesystem):

The build stage with the Go toolchain is about 800MB. The final image is literally just your binary — often 10–20MB. That is a 97% reduction. This is why Go is so popular for containerized microservices.

4. Docker Compose for Local Development

Real applications almost never run in isolation. Your web app needs a database. It probably needs a cache like Redis. Maybe it needs a message queue. Running each of these with separate docker run commands — remembering all the port mappings, volume mounts, environment variables, and network configurations — is painful and error-prone.

Docker Compose solves this. You define all your services in a single docker-compose.yml file, and one command (docker compose up) starts everything together in an isolated network where services can talk to each other by name.

Complete Example: Python App + PostgreSQL + Redis

Let us break this down piece by piece:

Services

Each service is a container. We have three: app (our Python application), db (PostgreSQL), and redis (Redis cache).

• build: . — Tells Docker Compose to build the app service from the Dockerfile in the current directory. The db and redis services use image: instead, which pulls pre-built images from Docker Hub.
• ports: "8000:8000" — Maps port 8000 on your host machine to port 8000 inside the container. The format is host:container.
• environment: — Sets environment variables inside the container. Notice the database URL uses db as the hostname, not localhost. This is Docker networking — services in the same Compose network can reach each other by their service name.
• depends_on: — Tells Compose to start db and redis before starting app. Note that this only waits for the container to start, not for the service inside to be ready. PostgreSQL might still be initializing when your app tries to connect. For production, use healthchecks.

Volumes: Persistent Data and Live Reloading

There are two different types of volumes in this file, and understanding the difference is critical:

• Named volume (pgdata:/var/lib/postgresql/data): This creates a Docker-managed volume that persists even when you destroy and recreate the container. Your database data survives docker compose down. Without this volume, you would lose all your data every time you restart the database container. Named volumes are defined in the top-level volumes: section at the bottom of the file.
• Bind mount (.:/app): This maps your current project directory on your host machine to /app inside the container. When you edit a file on your laptop, the change is instantly visible inside the container. This is essential for development — you edit code locally with your IDE, and the container sees the changes immediately. Combined with a file watcher (like Flask's debug mode or nodemon), your app reloads automatically.

Networking: Services Talk by Name

Docker Compose automatically creates a network for all the services defined in the file. Every service can reach every other service by using the service name as the hostname. That is why the database URL is postgresql://myuser:mypass@db:5432/mydb — the hostname db is the service name. Your app does not need to know the IP address of the database container. Docker's internal DNS resolves db to the correct container automatically.

This is also why you should never use localhost in your connection strings when using Docker Compose. Inside the app container, localhost refers to the app container itself, not to the database. Use the service name.

Essential Commands

5. Common Mistakes That Will Cost You Hours

These are the mistakes that every beginner makes and that every tutorial glosses over. Each one has wasted real hours of real developers' time.

Mistake 1: Running Containers as Root

By default, processes inside Docker containers run as root. This is a security risk. If an attacker exploits a vulnerability in your application, they have root access inside the container — and depending on your Docker configuration, that might give them a path to the host system.

The fix is simple. Add a USER directive to your Dockerfile:

Now your application runs as appuser instead of root. If the application is compromised, the attacker has limited permissions. This is a best practice for any production container.

Mistake 2: No .dockerignore File

We covered this in Section 2, but it is worth repeating because it is the most common mistake. Without a .dockerignore file, your build context includes everything in your project directory. A typical Node.js project with node_modules sends 200–500MB to the Docker daemon for every build. With a .dockerignore, it sends 5–10MB. Your builds will be 10x–50x faster.

If your Docker build feels slow, the first thing to check is whether you have a .dockerignore file. The second thing to check is whether it actually excludes node_modules and .git.

Mistake 3: Putting Secrets in the Dockerfile

Never do this:

Every instruction in a Dockerfile creates a layer, and layers are stored in the image. Anyone who has access to your image can inspect it and extract your secrets. Even if you delete the variable in a later layer, it still exists in the earlier layer.

Instead, pass secrets at runtime:

The .env file stays on your machine and is listed in .dockerignore and .gitignore. The secrets exist only at runtime, not baked into the image.

Mistake 4: Huge Images from Bad Base Images

The default Node.js image (node:20) is based on Debian and weighs about 1.1GB. The Alpine variant (node:20-alpine) is about 180MB. The slim variant (node:20-slim) is about 250MB. If you are not using Alpine or slim, you are shipping an extra gigabyte of operating system tools that your application never uses.

Always use the smallest base image that works:

• alpine variants — smallest, around 5MB base. Some packages need extra work to compile (they use musl instead of glibc), but for most applications they work fine.
• slim variants — middle ground, around 80MB base. Uses glibc, so all packages work. Good choice if Alpine causes compatibility issues.
• Default (Debian) — only use this if you specifically need tools or libraries that are not available on Alpine or slim.

Mistake 5: Not Pinning Versions

This Dockerfile works today and breaks tomorrow:

Without a version tag, Docker pulls the latest tag, which points to whatever the most recent version is. When Node.js releases version 22 and the latest tag updates, your build might break because of breaking changes you did not expect.

Always pin your versions:

This ensures your builds are reproducible. The same Dockerfile produces the same image today, next week, and next year.

Mistake 6: Bad Layer Ordering (Slow Builds)

Docker caches layers from top to bottom. When a layer changes, every layer after it is rebuilt. This means the order of your Dockerfile instructions directly affects build speed.

In the wrong version, every time you change any file in your project, Docker has to reinstall all dependencies because the COPY . . layer changed and invalidated the npm ci cache. In the correct version, dependencies are only reinstalled when package.json or package-lock.json changes. Your code changes (which happen constantly) only invalidate the final COPY layer.

The general rule: order layers from least frequently changed (base image, system dependencies) to most frequently changed (your application code). Dependencies change less often than code, so they should come first.

Mistake 7: Not Combining RUN Commands

Each RUN instruction creates a new layer. If you install packages in one layer and clean up in the next, the cleanup does not actually reduce the image size — the installed packages still exist in the earlier layer.

In the correct version, the build tools are installed, used, and removed in a single layer. The final layer does not contain the build tools, so the image is smaller.

6. When to Use Docker (And When Not To)

Docker is not always the right tool. Knowing when to use it is as important as knowing how to use it.

Use Docker When:

• Your application has external dependencies — databases, caches, message queues, or other services. Docker Compose lets you define and run all of them with one command. This is the strongest use case for Docker in development.
• You need consistent environments — when multiple developers work on the same project, or when your development and production environments need to match. "Works on my machine" disappears when everyone runs the same containers.
• You are deploying to the cloud — AWS ECS, Google Cloud Run, Azure Container Apps, Kubernetes, and most modern deployment platforms are container-native. Docker is the standard way to package and ship applications to these platforms.
• You are building microservices — each service gets its own container with its own dependencies, runtime, and scaling rules. A Python API, a Node.js frontend, and a Go data processor can all coexist without dependency conflicts.
• Your CI/CD pipeline needs reproducibility — build your image once, run tests inside it, and deploy the exact same image to production. No more "the tests passed but production broke" because the environments are literally identical.

Docker in CI/CD

A typical Docker-based CI/CD pipeline looks like this:

The image you tested is the image you deploy. There is no separate build step on the production server. No "did we install the right dependencies?" No "is the Node version the same?" The answer is always yes, because it is the same image.

Do NOT Use Docker When:

• You are building a simple static site. If your project is HTML, CSS, and JavaScript with no server, just deploy it to Vercel, Netlify, or GitHub Pages. These platforms handle hosting, CDN, and SSL for free. Docker adds complexity with zero benefit here.
• You are developing on macOS and Docker Desktop is slowing you down. Docker Desktop on Mac runs a Linux VM behind the scenes (remember: containers need a Linux kernel). File system operations between your Mac and the VM are slow — especially with bind mounts. If your development workflow feels sluggish, Docker Desktop's file I/O overhead might be the reason. Consider using native tools for development and Docker only for testing and deployment.
• You do not understand what Docker is doing. This might sound obvious, but if you are copying a Dockerfile from a tutorial without understanding what each line does, you are creating a black box that will break in ways you cannot debug. Learn the basics first (which you are doing now by reading this guide), then use Docker.
• Your application is a simple script or tool. If you are writing a Python script that processes a CSV file, you do not need Docker. Just use a virtual environment. Docker is for applications that need to run consistently across different machines, not for every piece of code you write.
• The team is not ready. If you are the only person on a team who knows Docker and you introduce it, you have created a dependency on yourself. Docker is a team tool. If the team does not understand it, every Docker-related issue becomes your problem.

A Decision Framework

Ask yourself these questions:

1. Does my application need external services (database, cache, queue)? If yes, Docker Compose will save you time.
2. Do I need the same environment across development, testing, and production? If yes, Docker images guarantee that.
3. Am I deploying to a cloud platform that expects containers? If yes, you need Docker (or a compatible alternative like Podman).
4. Is my project complex enough to justify the overhead? A single-file Python script does not need Docker. A full-stack app with a database and background workers probably does.

If you answered "no" to all four, you probably do not need Docker right now. That does not mean you should not learn it — it means you should learn it on a project where it provides real value, not add it to a project where it just adds complexity.