Detailed study notes on Docker: what it is, Dockerfiles, container management, image handling, lifecycle, restart policies, volumes, networks, environment variables, and registry operations.

1. What is Docker?
2. Docker Architecture
3. Dockerfile — Build Your Own Image
4. docker run — All Important Flags
5. What Could Go Wrong With Your App?
6. Docker Container Commands
7. Docker Container Lifecycle
8. Docker Container Restart Policies
   • --restart always
   • --restart unless-stopped
   • --restart on-failure
   • Policy Comparison
9. Docker Image Commands
10. Image Layers — How Docker Images Work
11. Environment Variables in Docker
12. Docker Volumes — Persistent Data
13. Docker Networks
14. Dangling Images
15. Push Image to Docker Hub
16. Pull Image from Docker Hub
17. Quick Reference Cheat Sheet

Docker is a platform that lets you package your application and all its dependencies into a single unit called a container, which can run identically on any machine that has Docker installed.

Without Docker:
  "It works on my machine!" ← classic problem
  Dev machine has Node 18, production has Node 16 → app breaks

With Docker:
  You package Node 18 + your code + dependencies inside the container
  The container runs the same everywhere: dev, staging, production

Key insight: Containers share the host OS kernel — they are not full virtual machines. This makes them lightweight and fast.

  You (terminal)
       │
       │  docker build / docker run / docker pull
       ▼
  Docker CLI  ──────────────────►  Docker Daemon (dockerd)
                                          │
                        ┌─────────────────┼─────────────────┐
                        ▼                 ▼                 ▼
                   [ Images ]       [ Containers ]     [ Volumes ]
                        │
                        ▼
                   Docker Hub / Registry
                   (docker pull/push)

• CLI sends commands to the Daemon via a REST API
• Daemon does the actual work: pulling images, starting containers, managing networks
• Images are pulled from registries (Docker Hub by default)
• Containers are created from images by the daemon

A Dockerfile is a plain text file with step-by-step instructions for building a Docker image. Docker reads it top to bottom and executes each instruction as a layer.

FROM node:20-alpine

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 5000

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

FROM node:20-alpine

• Every Dockerfile must start with FROM
• Sets the base image — your image is built on top of this
• node:20-alpine = Node.js v20 on Alpine Linux (a tiny 5MB Linux distro)
• Alpine is preferred over the default Debian because it's much smaller

node:20           → ~1.1 GB  (full Debian)
node:20-slim      → ~240 MB  (stripped Debian)
node:20-alpine    → ~130 MB  (Alpine Linux)  ← best for production

WORKDIR /app

• Sets the working directory inside the container for all following commands
• If /app doesn't exist, Docker creates it automatically
• All RUN, COPY, CMD instructions after this work relative to /app
• Without WORKDIR, files would land in / (root) which is messy

ENV NODE_ENV=production

• Sets an environment variable inside the image
• This variable is available to the app at runtime: process.env.NODE_ENV === 'production'
• Setting NODE_ENV=production tells Express and many npm packages to use production optimizations (less logging, no dev error pages, etc.)

COPY package*.json ./

• Copies files from your local machine into the image
• package*.json matches both package.json and package-lock.json
• ./ means the current directory inside the container (/app because of WORKDIR)
• Why copy package files before the rest of the code? → Layer caching (explained in Section 10)

RUN npm ci --only=production

• Executes a command during the image build (not at runtime)
• npm ci = clean install — uses package-lock.json exactly (more reliable than npm install)
• --only=production = skip devDependencies (testing tools, linters) → smaller image
• This creates a layer with all the installed node_modules

npm ci vs npm install:

COPY . .

• Copies everything else from your project directory into /app in the image
• This comes AFTER npm ci on purpose — if you change your code, only this layer rebuilds (not npm ci). See Section 10 for why.

What gets copied? Everything in the build context (.). Use a .dockerignore file to exclude node_modules, .git, .env, etc.

EXPOSE 5000

• Documents that the container listens on port 5000
• This is informational only — it does NOT actually publish the port to your host machine
• To actually access the port, you still need -p 5000:5000 in docker run
• Think of it as documentation: "this container serves traffic on 5000"

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

• Specifies the default command to run when the container starts
• Uses JSON array format (exec form) — preferred because it doesn't spawn a shell
• Runs node index.js which starts the Express server
• There can only be one CMD per Dockerfile (last one wins)

CMD vs ENTRYPOINT:

# CMD — can override:
CMD ["node", "index.js"]
# docker run my-app node other-script.js  ← overrides CMD

# ENTRYPOINT — always runs:
ENTRYPOINT ["node"]
CMD ["index.js"]           # ← this becomes the default argument to node
# docker run my-app other-script.js  ← runs "node other-script.js"

# Build the image from the Dockerfile in the current directory
docker build -t my-express-app .

# Run it, mapping port 5000 on host to 5000 in container
docker run -d -p 5000:5000 my-express-app

# Visit http://localhost:5000 → "Hello World from docker!"

Create a .dockerignore file alongside your Dockerfile:

node_modules
.git
.env
*.log
.DS_Store

Without this, COPY . . would copy node_modules (heavy) and .env (sensitive) into the image — bad for both size and security.

docker run is the most used command. Here are all the key flags with examples:

docker run [OPTIONS] IMAGE [COMMAND]

docker run \
  -d \
  -p 5000:5000 \
  --name my-express-app \
  -e NODE_ENV=production \
  -e PORT=5000 \
  --restart unless-stopped \
  --memory 256m \
  --cpus 0.5 \
  my-express-app

docker run --rm node:20-alpine node -e "console.log('hello')"

The container is deleted the moment it exits. Perfect for one-off tasks where you don't need the container to stick around.

This is the core reason Docker has restart policies and container lifecycle management. A production app can go down for many unexpected reasons:

Without restart policies, every one of these events means manual intervention to bring the app back. With the right policy, Docker handles recovery automatically.

The image above shows the 13 essential container commands. Here is the full reference with notes:

docker run nginx               # Create + start (foreground, blocks terminal)
docker run -d nginx            # Detached mode — runs in background, prints container ID
docker run -p 8080:80 nginx    # Port mapping: host:container

Port mapping breakdown:

docker run -p 8080:80 nginx
              ↑    ↑
         host port  container port

→ You access http://localhost:8080
→ Docker forwards it to port 80 inside the container

docker ps       # only RUNNING containers
docker ps -a    # ALL containers (including stopped/exited ones)

Output columns explained:

CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS         PORTS                  NAMES
a1b2c3d4e5f6   nginx   ...       1 min     Up 1 minute    0.0.0.0:8080->80/tcp   my-nginx
f6e5d4c3b2a1   nginx   ...       5 min     Exited (0)                            old-nginx

• STATUS: Up = running
• STATUS: Exited (0) = stopped cleanly
• STATUS: Exited (1) = stopped with an error

docker stop container_id      # Sends SIGTERM → waits 10 sec → sends SIGKILL (graceful)
docker start container_id     # Starts a stopped container (keeps previous config)
docker restart container_id   # Equivalent to docker stop + docker start

docker stop vs docker kill:

• stop = graceful shutdown (app can clean up, close connections)
• kill = immediate force kill (SIGKILL, no cleanup time)

docker rm container_id         # Remove one stopped container
docker container prune         # Remove ALL stopped containers
docker system prune            # Remove stopped containers + dangling images + unused networks + build cache

You cannot docker rm a running container. Stop it first, or use docker rm -f to force-remove.

docker logs container_id             # Print all logs since container started
docker logs -f container_id          # Follow logs in real time (like tail -f)
docker logs --tail 100 container_id  # Show last 100 lines only
docker logs --since 1h container_id  # Show logs from the last 1 hour

docker exec -it container_id sh     # Open shell (sh is available in most images)
docker exec -it container_id bash   # Bash (available in Debian/Ubuntu-based images)

• -i = interactive (keeps stdin open)
• -t = allocate a terminal (TTY)
• You can also run single commands: docker exec container_id ls /app

The diagram shows 4 states a container moves through and the commands that trigger each transition.

                  ┌─────────────── Run ───────────────────┐
                  │                                        ▼
   Create ──► [ Created ] ──── Start ────────────► [ Running ]
                  │                                        │
                  │ rm                                   Stop
                  │                                        │
                  ▼                                        ▼
             [ Deleted ] ◄──────── rm ──────────── [ Stopped ]
                                                          │
                                                        Start
                                                          │
                                                          └──────────────► [ Running ]

Key insight from the diagram: docker run goes directly to Running — it never enters the Created state. Only docker create produces a Created container.

The diagram shows 3 restart policies branching from the top. These are set when creating a container:

docker run --restart <policy> image_name

docker run --restart always nginx

What the flowchart shows:

Container Start ──────────────────────► Container Exit
      ▲                                       │
      │                                       ▼
      └──────────── Restart Container ◄───────┘
                          ▲
                          │
                  Docker Daemon Restart

Behavior summary:

• Restarts on clean exit (exit code 0) ✅
• Restarts on crash (exit code != 0) ✅
• Restarts after Docker daemon restart / system reboot ✅
• This is a permanent loop — the container will always come back

Use case: Web servers, databases, APIs — anything that must never be offline.

docker run -d --restart always -p 80:80 nginx

docker run --restart unless-stopped nginx

What the flowchart shows:

Container Start ──────────────────────────────► Container Exit
      ▲                                               │
      │                                               ▼
      │                                       Manually Stopped?
      │                                        Yes │      │ No
      │                                            ▼      ▼
      │                                      Don't    Restart
      │                                      Restart  Container ──┐
      │                                                           │
      └───────────────────────────────────────────────────────────┘

  Docker Daemon Restart
          │
          ▼
   Was Running Before?
    Yes │        │ No
        ▼        ▼
   Restart   Don't
   Container  Restart

Behavior summary:

• Restarts on crash ✅
• Restarts on clean exit ✅
• Respects docker stop — will NOT come back after a manual stop ✅
• After daemon restart — only if it wasn't manually stopped ⚠️

Key difference from always: always ignores your manual stop. unless-stopped remembers it and stays stopped after daemon restarts too.

Use case: Production services where you occasionally need to take them offline for maintenance.

docker run -d --restart unless-stopped -p 3000:3000 my-app

docker run --restart on-failure nginx

# With a max retry limit:
docker run --restart on-failure:5 nginx

What the flowchart shows:

Container Start ──────────────────────────────► Container Exit
      ▲                                               │
      │                                               ▼
      │                                       Exit Code != 0 ?
      │                                        Yes │      │ No
      │                                            ▼      ▼
      │                                       Restart   Don't
      │                                       Container  Restart
      └───────────────────────────────────────────┘

  Docker Daemon Restart
          │
          ▼
     Restart Container
          │
          └──────────────────────────────► Container Start

Behavior summary:

• Restarts on crash (exit code != 0) ✅
• Does NOT restart on clean exit (exit code 0) ❌ — intentionally won't restart a finished job
• Restarts after Docker daemon restart ✅
• :N limits max retries — e.g., on-failure:5 = give up after 5 consecutive crashes

Use case: One-time scripts, batch jobs, or worker processes that should finish and stop cleanly, but automatically retry if they crash.

# Data import job — retry up to 3 times if it crashes, stop when done
docker run --restart on-failure:3 my-data-importer

Taken directly from the image:

Extended comparison:

Images are the templates/blueprints that containers are created from. An image is read-only — when you run it, Docker adds a writable layer on top to create a container.

docker build -t my-app .              # Build and tag as "my-app:latest"
docker build -t my-app:v2 .           # Build with specific version tag
docker build -f Dockerfile.prod -t my-app:prod .  # Use a different Dockerfile
docker build --no-cache -t my-app .   # Force rebuild all layers (ignore cache)

The . at the end is the build context — the directory Docker reads files from.

docker rmi nginx           # remove by name
docker rmi a6bd71f48f68    # remove by image ID
docker rmi nginx:1.25      # remove specific tag

Cannot remove an image that is being used by an existing container (even stopped). Remove the container first.

docker tag my-app my-app:v1                      # add a version tag
docker tag my-app username/my-app:latest         # tag for Docker Hub push

Tagging does NOT copy the image — it just adds a new label pointing to the same image data.

docker inspect nginx

Returns a JSON object with: Image ID, creation date, environment variables, exposed ports, entrypoint, CMD, layer info, volume mounts.

Every instruction in a Dockerfile that modifies the filesystem creates a new layer. Layers are stacked on top of each other to form the final image.

┌──────────────────────────────┐
│  Layer 5: COPY . .           │  ← your app source code
├──────────────────────────────┤
│  Layer 4: RUN npm ci         │  ← node_modules
├──────────────────────────────┤
│  Layer 3: COPY package*.json │  ← package files
├──────────────────────────────┤
│  Layer 2: ENV NODE_ENV=...   │  ← env config
├──────────────────────────────┤
│  Layer 1: FROM node:20-alpine│  ← base OS + Node
└──────────────────────────────┘

Docker caches each layer. When you rebuild, Docker only re-runs layers that changed and everything after them.

Smart order (this project's Dockerfile):

COPY package*.json ./      # Layer A — only changes when dependencies change
RUN npm ci                 # Layer B — only re-runs if Layer A changed
COPY . .                   # Layer C — changes every time you edit code

You change a .js file:
  Layer A (package.json) → cache HIT  ← not re-run
  Layer B (npm ci)       → cache HIT  ← not re-run  ← saves minutes
  Layer C (COPY . .)     → cache MISS ← re-run (your file changed)

Naive order (bad):

COPY . .           # Changes every time → cache busted
RUN npm ci         # Always re-runs → slow!

Rule: Put rarely changing instructions first, frequently changing ones last. This maximizes cache hits and makes builds fast.

Environment variables let you configure your app without changing the code or rebuilding the image. There are two ways to set them in Docker.

ENV NODE_ENV=production
ENV PORT=5000

• The variable is built into the image — every container from this image gets it
• Available at both build time and runtime
• Good for variables that are always the same (e.g., NODE_ENV=production)

docker run -e PORT=3000 my-app
docker run -e NODE_ENV=development my-app
docker run -e DB_URL=mongodb://localhost:27017/mydb my-app

• Overrides or adds variables when starting the container
• Does NOT change the image — different containers can have different values
• Good for secrets, database URLs, API keys — things that differ per environment

# .env file:
NODE_ENV=production
PORT=5000
DB_PASSWORD=supersecret

docker run --env-file .env my-app

• Loads all variables from a file — cleaner than many -e flags
• Never bake .env files into your image — use --env-file or a secrets manager

--env-file < -e flag < ENV in Dockerfile
                ↑
         -e flag overrides --env-file

Actually: -e flag always overrides --env-file values, so runtime flags take precedence.

// index.js
const port = process.env.PORT || 5000;
const env  = process.env.NODE_ENV;

console.log(`Running in ${env} mode on port ${port}`);

By default, a container's filesystem is temporary. When the container is deleted, all data written inside it is gone. Volumes solve this.

Container (no volume):
  You write data to /app/data inside the container
  docker rm container
  → All data is permanently lost

# Create a named volume
docker volume create my-data

# Use it when running a container
docker run -v my-data:/app/data my-app

# List all volumes
docker volume ls

# Inspect a volume (see where Docker stores it)
docker volume inspect my-data

# Remove a volume
docker volume rm my-data

# Remove all unused volumes
docker volume prune

• Docker stores the volume data on the host (usually under /var/lib/docker/volumes/)
• The volume persists even after the container is removed
• Multiple containers can share the same volume

# Mount current directory into /app in the container
docker run -v $(pwd):/app my-app

# Windows (PowerShell):
docker run -v ${PWD}:/app my-app

# Mount a specific host path
docker run -v /Users/zihad/myproject:/app my-app

Use case for local development:

# Your code changes on host are instantly reflected in the container
docker run -d -p 5000:5000 -v $(pwd):/app my-express-app

Bind mounts are great for dev (see live code changes), but named volumes are better for production (Docker manages the location and lifecycle).

Without volume:                   With named volume:
  Container deleted                 Container deleted
  → data gone ❌                    → volume persists ✅

  New container                     New container
  → starts empty ❌                 → mounts same volume, data intact ✅

By default, containers are isolated — they can't talk to each other. Networks allow containers to communicate.

Docker creates three networks automatically:

docker network ls
# NETWORK ID   NAME      DRIVER    SCOPE
# abc123       bridge    bridge    local
# def456       host      host      local
# ghi789       none      null      local

On the default bridge network, containers cannot reach each other by name — only by IP. A custom bridge network enables DNS-based discovery (container name = hostname).

# Create a custom network
docker network create my-network

# Run containers on that network
docker run -d --name app --network my-network my-express-app
docker run -d --name db  --network my-network mongo

# Now "app" can connect to "db" just by using the hostname "db"
# e.g., mongodb://db:27017/mydb

# List networks
docker network ls

# Create a network
docker network create my-network

# Inspect a network (see which containers are connected)
docker network inspect my-network

# Connect a running container to a network
docker network connect my-network container_id

# Disconnect a container from a network
docker network disconnect my-network container_id

# Remove a network
docker network rm my-network

# Remove unused networks
docker network prune

Without custom network:              With custom network:
  container A → cannot find "db"      container A → "db" resolves to db container IP
  must use IP: 172.17.0.2             can use: mongodb://db:27017

Real example — Express app + MongoDB:

docker network create app-net

docker run -d \
  --name mongo \
  --network app-net \
  mongo

docker run -d \
  --name express-app \
  --network app-net \
  -p 5000:5000 \
  -e DB_URL=mongodb://mongo:27017/mydb \
  my-express-app

The Express app connects to MongoDB using mongodb://mongo:27017 — mongo resolves to the MongoDB container's IP automatically.

A dangling image is an image with no name and no tag — it appears as <none>:<none> in docker images. It exists on disk but no container or tag references it.

The most common cause is rebuilding an image with the same tag:

# Build 1 — image created, tagged as "my-app:latest"
docker build -t my-app .

# ... you edit your code ...

# Build 2 — a NEW image gets the "my-app:latest" tag
# The OLD image LOSES its tag → becomes <none>:<none> (dangling)
docker build -t my-app .

Every rebuild leaves the old image orphaned. Over many rebuilds, these pile up and eat disk space silently.

docker images

# REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
# my-app       latest    abc123def456   30 seconds ago   320MB
# <none>       <none>    d1e017099d17   5 minutes ago    310MB   ← dangling
# <none>       <none>    a2f9b3c44e21   1 hour ago       308MB   ← dangling

docker images -f dangling=true

• Waste disk space — each build can leave behind hundreds of MBs
• Accumulate invisibly — don't show up clearly in plain docker images
• Serve no purpose — no container runs from them, no tag points to them

# Remove only dangling images
docker image prune

# Remove ALL images not currently used by a container
docker image prune -a

# Skip confirmation prompt
docker image prune -f

# Remove everything unused (containers, images, networks, cache)
docker system prune

Docker Hub is the default public registry. Once an image is pushed, anyone can docker pull it from anywhere in the world.

Your Machine                   Docker Hub
─────────────                  ──────────────────────────────
[local image]  ─── push ──►   [username/repository:tag]

docker login
# Prompts for username and password

docker build -t my-app .

Docker Hub requires the format: username/repository:tag

# Format:
docker tag <local-image-name> <dockerhub-username>/<repository>:<tag>

# Example:
docker tag my-app zihadrahman/my-app:v1
docker tag my-app zihadrahman/my-app:latest

docker push zihadrahman/my-app:v1
docker push zihadrahman/my-app:latest

Docker pushes each layer separately. Layers already on Docker Hub are skipped (Layer already exists), so subsequent pushes are very fast.

Your image is now at: hub.docker.com/r/zihadrahman/my-app

Anyone can pull it with:

docker pull zihadrahman/my-app:v1

docker login

docker build -t my-express-app .

docker tag my-express-app zihadrahman/my-express-app:v1
docker tag my-express-app zihadrahman/my-express-app:latest

docker push zihadrahman/my-express-app:v1
docker push zihadrahman/my-express-app:latest

• :latest — always points to the most recent build (default pulled by others)
• :v1 — a permanent snapshot. Even after you push v2, v1 remains pullable.

Pulling downloads a Docker image from a registry to your local machine so you can run containers from it.

docker pull nginx           # pulls nginx:latest
docker pull nginx:1.25      # pulls a specific version
docker pull node:20-alpine  # the exact base image this project uses

Docker images are made of layers. Docker downloads each layer separately and caches them:

docker pull node:20-alpine

18-alpine: Pulling from library/node
31e352740f53: Pull complete      ← base OS layer
b2b5bfcb75ab: Pull complete      ← node runtime layer
Digest: sha256:abc123...
Status: Downloaded newer image for node:20-alpine

If you pull another image that shares a layer, that layer is not re-downloaded — reused from cache.

# Official image (maintained by Docker/vendor)
docker pull nginx
docker pull postgres

# User/community image (username/repository)
docker pull zihadrahman/my-express-app:v1

# Specific version tag
docker pull nginx:1.25.3

# Immutable digest reference (exact version, never changes)
docker pull nginx@sha256:abc123...

Use docker pull when you want to pre-download an image without running it (useful for warming CI/CD cache).