1.17 Docker Basics

1. Docker's Purpose and Boundaries

SSJ: "It works on my machine, why doesn't it work on yours?"

SSSJ: "I don't know, the error says some library is missing..."

SSSSJ: "You can't even install this? You're missing... you %￥#*...?"

The cause of such problems is usually not the code itself but the environment — the operating system, CPU architecture, dependency library versions, configuration, and environment variables; a difference in any of them can lead to different results. Docker can solidify and package a significant part of the runtime environment, but it cannot solve all differences.

Docker is an open-source containerization platform. It packages "application + runtime environment" into an image, distributes it through a registry; others pull the image and run it as a container on machines with Docker installed, saving the step of installing dependencies and configuring the environment. This mechanism is explained one by one in 2.2.

An image packages the application and its user-space dependencies, at least solving problems like "dependency version mismatch". But containers share the host's Linux kernel; CPU architecture, mounted files, environment variables, networking, and external services still affect the results, so "using the same image" does not mean "the results are guaranteed to be identical".

2. Core Concepts

2.1 Containers vs Virtual Machines

Containers generally don't include a full guest OS, so startup and footprint are usually smaller than VMs.

How big the difference actually is still depends on the image, workload, and which machine it runs on.

2.2 Four Core Concepts

3. Installing Docker

3.1 Windows / macOS

Just install Docker Desktop; it bundles the GUI, Docker CLI, Compose, and more. Before installing, check the system requirements, organization license, and the virtualization backend you plan to use.

3.2 Linux

Different distributions have different installation and upgrade methods. For Ubuntu, follow the official Docker Engine installation docs to configure Docker's apt repository, then install Engine, Buildx, and the Compose plugin.

Don't mix distribution-bundled packages, third-party scripts, and official repositories.

3.3 Verify the Installation

docker --version          # Check the version
docker run --rm hello-world # Run the test image; the test container is removed after it exits

If the container exits normally and prints the welcome message, the chain of Docker client, daemon, and image pulling is working.

4. Basic Operations

4.1 Image Operations

# Search for images
docker search nginx

# Use the version tag chosen by the project; avoid accidentally following latest
docker pull python:3.12
docker pull python:3.12-slim     # Slim variant, smaller size

# List local images
docker images

# Delete an image
docker rmi python:3.12

4.2 Container Operations

# Run containers
docker run hello-world                # Run and exit
docker run -it ubuntu:24.04 bash          # Interactively enter Ubuntu
docker run -d nginx:1.28-alpine           # Run in the background
docker run --name myweb nginx:1.28-alpine # Name the container
docker run -p 8080:80 nginx:1.28-alpine   # Port mapping (host 8080 -> container 80)
docker run --rm -v "$(pwd):/app" node:22 node --version # Bind-mount the current directory and run an explicitly versioned image

# View containers
docker ps                # Running containers
docker ps -a             # All containers (including stopped ones)

# Control containers
docker start <name/id>    # Start
docker stop <name/id>     # Stop
docker restart <name/id>  # Restart
docker rm <name/id>       # Delete a container

# Enter a running container
docker exec -it <name> sh              # The image may not include bash

# View logs
docker logs <name>
docker logs -f <name>       # Follow the output

4.3 Detailed Explanation of run Parameters

docker run is the most commonly used command; here are the parameter meanings:

Verify: run docker run --rm -p 127.0.0.1:8080:80 nginx:1.28-alpine and open http://localhost:8080 in a browser; seeing the nginx welcome page means it works. Binding to 127.0.0.1 avoids exposing this practice service to the LAN.

Press Ctrl + C to stop the container when done.

5. Dockerfile: Building Your Own Image

5.1 Basic Structure

A Dockerfile is a text instruction manual that tells Docker how to assemble our own image on top of a base image. Example:

# Dockerfile
# Base image
FROM python:3.12-slim

# Set the working directory
WORKDIR /app

# Copy the dependency file and install (use layer caching)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the project code
COPY . .

# Declare the port
EXPOSE 8000

# Startup command
CMD ["python", "app.py"]

The example assumes requirements.txt and app.py already exist in the build context, and only illustrates the instruction order. It runs as the base image's default user, with no health checks, non-root user, dependency hashes, or production-grade server, so it should not be used directly as a production template.

5.2 Common Instructions

5.3 Build and Run

# Build the image (-t sets the name, . is the context directory)
docker build -t myapp:1.0 .

# Run
docker run -p 8000:8000 myapp:1.0

Verify: after docker images, you should see myapp. Then visit http://localhost:8000; if the app responds, both the build and the run are working.

5.4 Build Tips

5.4.1 Use Layer Caching

Put the steps that change rarely first. Put COPY requirements.txt + RUN pip install before COPY . ., so that changing code doesn't reinstall dependencies and the build is much faster.

5.4.2 Use .dockerignore

Same idea as .gitignore: keep files that shouldn't enter the image out:

# .dockerignore
node_modules
.git
__pycache__
.env
.venv

6. Docker Hub: The Image Registry

Docker Hub is Docker's official public image registry, containing official images, images from verified publishers, and plenty of community images. Before pulling, check the namespace, maintainer, tags, supported architectures, and update frequency — a good name doesn't mean it can be trusted.

# Log in
docker login

# Tag the image (username/image-name:version)
docker tag myapp:1.0 your-username/myapp:1.0

# Push
docker push your-username/myapp:1.0

# Pull
docker pull your-username/myapp:1.0

7. Data Persistence

Once a container is deleted, its writable layer is gone too. Data that must survive across container lifecycles should go into a volume, a bind mount, or external storage, and be backed up separately.

# Named volume (managed by Docker)
docker volume create mydata
docker run -d --name mysql-demo \
  -e MYSQL_ROOT_PASSWORD="$MYSQL_ROOT_PASSWORD" \
  -v mydata:/var/lib/mysql \
  mysql:8.4

# Bind mount (mount the current project read-only into the container)
docker run --rm -v "$PWD:/app:ro" -w /app node:22 ls

Before running the database example, set a non-empty MYSQL_ROOT_PASSWORD in the current Shell. A password written directly on the command line also stays in the shell history.

Passing it in through an existing environment variable is only for local practice; in a real environment, use the platform's secret management.

8. Docker Compose: Multi-Container Orchestration

Real projects are usually made up of multiple services (web + database + cache); running docker run one by one is tedious. Docker Compose describes all services in one YAML file and brings up the whole stack with a single command.

8.1 Example: compose.yaml

# Define a web service and a database with persistent storage.
services:
  web:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_HOST: db

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?Set MYSQL_ROOT_PASSWORD}
    volumes:
      - dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -p\"$$MYSQL_ROOT_PASSWORD\""]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 20s

volumes:
  dbdata:

8.2 Operation Commands

docker compose up -d        # Start all services (background)
docker compose ps           # Check status
docker compose logs -f      # View logs
docker compose down         # Stop and remove containers and the default network
docker compose build        # Rebuild

Set MYSQL_ROOT_PASSWORD in an uncommitted .env or secure secret management before running; don't write real passwords into the Compose file.

depends_on with service_healthy waits for the example database's health check to pass before continuing. The short form only controls startup order; it doesn't guarantee the service is usable. Verify: first check the config with docker compose config --quiet, then start and check the status with docker compose ps. docker compose down doesn't remove the named volumes here by default; only explicitly adding --volumes clears the data along with them.

9. Common Student Scenarios

9.1 Start a Course Lab Environment from Config

When a course provides a Dockerfile or compose.yaml, build or bring up the environment according to the config; it saves the effort of manually installing a lot of user-space dependencies:

docker compose up

When the image version, config, architecture, and input data match, the lab environment is easier to reproduce.

But you should still check the results against the course requirements.

9.2 Install Databases Without Polluting Your Machine

Want to learn MySQL, Redis, or PostgreSQL without installing a bunch of them on your machine:

docker volume create mysql-data
docker run -d --name mysql \
  -p 127.0.0.1:3306:3306 \
  -e MYSQL_ROOT_PASSWORD="$MYSQL_ROOT_PASSWORD" \
  -v mysql-data:/var/lib/mysql \
  mysql:8.4

Set MYSQL_ROOT_PASSWORD in the current Shell before running. When done, stop the process with docker stop mysql — a stopped container no longer consumes runtime CPU and memory, but the container metadata, writable layer, image, and volume still occupy disk. Deleting mysql-data removes the database content along with it.

9.3 Deploy a Personal Project

After building the project into an image and pushing it to a Registry, the server can run it at a fixed image version. But production deployment also involves access control, secrets, networking, data migration, health checks, logging, monitoring, resource limits, and rollback — Docker itself won't handle these for you.

10. TODO Checklist

• Understand the relationships between images, containers, Registry, and volumes
• Try running an image with an explicit version tag and check the logs and exit status
• Try writing a simple Dockerfile that includes a .dockerignore
• Try checking the Compose config with docker compose config
• Make sure passwords and tokens aren't written into images, Dockerfiles, or repositories
• Make sure important data has a backup plan independent of containers and volumes

11. Questions Worth Thinking About

12. Further Reading

• Docker official documentation
• Docker Hub
• Dockerfile reference
• Compose documentation
• Docker Engine installation docs