Docker Images vs Containers Explained — How They Work and Why It Matters

# ── Stage 1: Install dependencies ────────────────────────────────────────────
# We use a specific version tag (not 'latest') so builds are reproducible.
# Alpine keeps the base image small (~5MB vs ~900MB for full Debian node image).
FROM node:20-alpine AS dependency-installer

WORKDIR /app

# COPY package files BEFORE source code — this is intentional.
# Docker caches this layer. If package.json hasn't changed, npm install
# is skipped on the next build even if your source code changed.
COPY package.json package-lock.json ./

# Install only production dependencies to keep the layer lean.
RUN npm ci --omit=dev

# ── Stage 2: Production image ─────────────────────────────────────────────────
# We start fresh from the same base. Only the artifacts we need come with us.
# The node_modules from Stage 1, the compiled source — nothing else.
FROM node:20-alpine AS production

WORKDIR /app

# Copy the pre-installed node_modules from the first stage.
# This means no build tools (npm, git, etc.) exist in the final image.
COPY --from=dependency-installer /app/node_modules ./node_modules

# Now copy the actual application source code.
# Because this COPY comes AFTER the node_modules copy, changing source code
# only invalidates the cache from this line forward — not the npm install.
COPY src/ ./src
COPY package.json ./

# Run as a non-root user. This is a security baseline, not optional.
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

# Document which port the app listens on. EXPOSE is metadata — it doesn't
# actually publish the port. You do that with -p at runtime.
EXPOSE 3000

# CMD is the default process. Using array form avoids shell interpretation
# issues and ensures signals (like SIGTERM from 'docker stop') reach the process.
CMD ["node", "src/server.js"]

#!/bin/bash
# This script walks through the full container lifecycle with a real example.
# We'll use the image we built in the previous section.

# ── 1. CREATE a container without starting it ─────────────────────────────────
# Useful when you want to inspect or configure before the process starts.
docker create \
  --name api-server-v1 \
  --publish 3000:3000 \
  my-node-api:1.0

# ── 2. START the created container ───────────────────────────────────────────
docker start api-server-v1

# Most of the time you combine create + start with 'docker run':
# docker run -d --name api-server-v1 -p 3000:3000 my-node-api:1.0
# -d means detached (runs in background). Without it, the terminal is attached
# to the container process and Ctrl+C kills the container.

# ── 3. INSPECT what is running ────────────────────────────────────────────────
# Shows PID, port bindings, mounted volumes, environment vars, and more.
docker inspect api-server-v1 --format '{{ .State.Status }}'
# Output: running

docker inspect api-server-v1 --format '{{ .NetworkSettings.IPAddress }}'
# Output: 172.17.0.2

# ── 4. CHECK live resource usage ─────────────────────────────────────────────
# Like 'top' but for containers. Shows CPU %, memory usage, and network I/O.
docker stats api-server-v1 --no-stream

# ── 5. STOP the container gracefully ─────────────────────────────────────────
# Docker sends SIGTERM to PID 1 inside the container, waits 10 seconds,
# then sends SIGKILL if the process hasn't exited. Respect the grace period
# in your app's signal handler for clean shutdowns.
docker stop api-server-v1

# ── 6. VERIFY it is stopped but still exists on disk ─────────────────────────
docker ps -a --filter name=api-server-v1
# The -a flag shows ALL containers, including stopped ones.

# ── 7. REMOVE the container entirely ─────────────────────────────────────────
# The writable layer is deleted. The image is untouched.
docker rm api-server-v1

# Shortcut to stop AND remove in one command:
# docker rm -f api-server-v1

#!/bin/bash
# Demonstrates a production-grade docker run command with volumes,
# environment config, resource limits, and restart policy.

# ── Create a named volume for the database data directory ─────────────────────
# Named volumes are managed by Docker and survive container removal.
# Bind mounts (host path:container path) are better for local dev but
# depend on the host filesystem layout, which is fragile in production.
docker volume create postgres-data

# ── Run a PostgreSQL container the right way ──────────────────────────────────
docker run \
  --detach \
  --name production-postgres \
  \
  # Mount the named volume to the data directory postgres uses internally.
  # This ensures database files persist across container replacements.
  --volume postgres-data:/var/lib/postgresql/data \
  \
  # Load sensitive credentials from a file that lives outside version control.
  # Never use --env POSTGRES_PASSWORD=secret inline — it shows in 'docker inspect'
  # and in shell history.
  --env-file ./config/postgres.env \
  \
  # Limit the container to 512MB RAM. Without this, a runaway query can
  # consume all host memory and crash other containers.
  --memory 512m \
  \
  # Restart unless we explicitly stop it. This handles server reboots and
  # OOM kills without needing a separate process supervisor.
  --restart unless-stopped \
  \
  # Only expose PostgreSQL to localhost — never to 0.0.0.0 in production.
  --publish 127.0.0.1:5432:5432 \
  \
  postgres:16-alpine

# ── Verify the volume is mounted correctly ────────────────────────────────────
docker inspect production-postgres \
  --format '{{ range .Mounts }}{{ .Name }}: {{ .Destination }}{{ end }}'

# ── Check the container is healthy ───────────────────────────────────────────
docker exec production-postgres pg_isready -U postgres

# ── Contents of config/postgres.env (NEVER commit this file) ─────────────────
# POSTGRES_USER=appuser
# POSTGRES_PASSWORD=a-very-long-random-secret-generated-by-a-password-manager
# POSTGRES_DB=appdb