Dockerizing Backend Applications

# .dockerignore — applies to ALL languages, adjust as needed
.git
.gitignore
.dockerignore

# Dependencies — rebuilt inside the image, never copied from host
node_modules
__pycache__
*.pyc
*.pyo
.venv
venv

# Test and development files
*.test.js
*.spec.js
tests/
__tests__/

# Local environment and secrets — never in the image
.env
.env.*
*.local

# Build output and caches
dist/
build/
.cache/
coverage/
.pytest_cache/

# Editor and OS files
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db

# Documentation
README.md
docs/
*.md

# syntax=docker/dockerfile:1
FROM node:18-alpine AS base
WORKDIR /app
COPY package*.json ./
# Copy only the dependency manifest first.
# As long as package.json doesn't change, this layer is cached —
# the npm install step below will never re-run on a code-only change.

# ────────────────────────────────────────────────────────
FROM base AS development
RUN npm install
# Install all dependencies including devDependencies.
# Source code is NOT copied — it will be mounted as a volume.
EXPOSE 3000
CMD ["npm", "run", "dev"]

# ────────────────────────────────────────────────────────
FROM base AS production
RUN npm install --omit=dev
# Production dependencies only — no test runners, type checkers, or build tools.
# --omit=dev is the modern equivalent of --production.

COPY . .
# Source code copied AFTER npm install so code changes don't bust the dep cache.

RUN addgroup -S appgroup && \
    adduser  -S appuser -G appgroup && \
    chown -R appuser:appgroup /app
# Create non-root user and transfer ownership of /app BEFORE switching.
# If you chown after USER, the command runs as appuser and may lack permission
# to chown files owned by root — a common and confusing failure mode.

USER appuser

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
# Orchestrators (Compose, Swarm, Kubernetes) use this to know when the app
# is ready to receive traffic. Without it, they assume ready on start.

EXPOSE 3000
CMD ["node", "server.js"]

# syntax=docker/dockerfile:1
FROM python:3.11-slim AS base
# python:3.11-slim — Debian-based, smaller than the full image, has pip.
# Avoid python:3.11-alpine for Python — many packages require C extensions
# that need build tools not present in Alpine, causing pip install to fail.

WORKDIR /app

# Create a virtual environment in a predictable location.
# This isolates pip installs from the system Python completely.
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
# Add the venv bin to PATH so `python` and `pip` always resolve to the venv.
# This ENV persists through all subsequent RUN, CMD, and ENTRYPOINT instructions
# and is inherited by the running container — non-root user included.

# ────────────────────────────────────────────────────────
FROM base AS builder
# Separate stage for building — keeps build tools out of the final image.
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
# --no-cache-dir prevents pip from writing a local cache — keeps the layer lean.
# Packages are installed into /opt/venv because PATH points there.

# ────────────────────────────────────────────────────────
FROM base AS production
# Copy only the installed venv from the builder stage — not the build tools.
COPY --from=builder /opt/venv /opt/venv

COPY . .

RUN addgroup --system appgroup && \
    adduser  --system --ingroup appgroup appuser && \
    chown -R appuser:appgroup /app /opt/venv
# Transfer ownership of both the app directory AND the venv.
# Without chowning /opt/venv, appuser can't read the installed packages.
# This was the bug described in the lesson introduction.

USER appuser

HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" \
  || exit 1

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
# 0.0.0.0 is required — the default 127.0.0.1 only accepts connections from
# within the container. Forgetting this is the most common Python/uvicorn gotcha.

# syntax=docker/dockerfile:1
FROM golang:1.22-alpine AS builder
# golang:1.22-alpine — full Go toolchain for compilation.
# This stage will NOT appear in the final image — it's discarded after build.

WORKDIR /build

# Copy dependency manifests first — cache the module download step.
COPY go.mod go.sum ./
RUN go mod download
# Downloads all dependencies into the module cache.
# Re-runs only when go.mod or go.sum changes — not on code changes.

COPY . .

# Compile the binary — CGO disabled for a fully static binary.
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
    go build \
    -ldflags="-w -s" \
    -o /app/payment-api \
    ./cmd/server
# CGO_ENABLED=0   → no C bindings — fully static binary, no libc dependency
# GOOS=linux      → target Linux regardless of build machine OS
# GOARCH=amd64    → target x86_64 — change for ARM deployments
# -ldflags="-w -s" → strip debug info and symbol table → smaller binary
# -o /app/payment-api → output path for the compiled binary

# ────────────────────────────────────────────────────────
FROM gcr.io/distroless/static:nonroot AS production
# distroless/static — contains ONLY:
# • CA certificates (for HTTPS calls)
# • /etc/passwd and /etc/group (for non-root user)
# • timezone data
# Nothing else. No shell. No curl. No apt. No sh.
# An attacker who gets code execution has almost no tools to work with.

COPY --from=builder /app/payment-api /payment-api
# Copy only the compiled binary from the builder stage.
# The entire Go toolchain, source code, and module cache are discarded.

# distroless:nonroot already defaults to uid 65532 (nonroot user).
# No USER instruction needed — it's baked into the base image.

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD ["/payment-api", "--health-check"]
# No shell available — HEALTHCHECK must use exec form, not shell form.
# The binary itself handles the --health-check flag.

EXPOSE 8080
ENTRYPOINT ["/payment-api"]

# Step 1 — create .dockerignore before writing a single Dockerfile line
cat > .dockerignore << 'EOF'
.git
node_modules
.env
.env.*
dist/
coverage/
*.test.js
README.md
EOF

# Step 2 — build the production image
docker build --target production -t acmecorp/payment-api:a3f2c8d .

# Step 3 — verify the image before pushing
# Check the size:
docker images acmecorp/payment-api:a3f2c8d
# Check who the process runs as:
docker run --rm acmecorp/payment-api:a3f2c8d whoami
appuser
# Check the health check is configured:
docker inspect acmecorp/payment-api:a3f2c8d \
  --format '{{json .Config.Healthcheck}}' | python3 -m json.tool

# Step 4 — run it and confirm health:
docker run -d --name payment-api -p 3000:3000 acmecorp/payment-api:a3f2c8d
docker ps
CONTAINER ID   NAME          STATUS
a1b2c3d4e5f6   payment-api   Up 12 seconds (health: starting)
# Wait 30 seconds (start-period):
docker ps
CONTAINER ID   NAME          STATUS
a1b2c3d4e5f6   payment-api   Up 45 seconds (healthy)

# Step 5 — push to registry
docker push acmecorp/payment-api:a3f2c8d