Dockerize Any Application the Right Way — Multi-Stage Builds & Best Practices

# Check if Docker is already installed
docker --version
# Expected: Docker version 24.x.x or higher
 
docker info | grep "Server Version"
# Expected: Server Version: 24.x.x

# Remove old versions
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null
 
# Install dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release
 
# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
 
# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
# Install Docker Engine, CLI, containerd, and plugins
# - docker-ce: the daemon (dockerd) that runs containers
# - docker-ce-cli: the `docker` command you type
# - containerd.io: the lower-level container runtime dockerd talks to
# - docker-buildx-plugin: enables `docker buildx` (BuildKit driver, multi-arch, cache mounts)
# - docker-compose-plugin: enables `docker compose` (multi-container orchestration,
#   used heavily in Day 3 to spin up Node.js + Postgres + Redis + Nginx as one stack)
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
 
# Add your user to the docker group.
# The Docker daemon's socket at /var/run/docker.sock is owned by root and
# group-owned by `docker` (mode 660). Members of the `docker` group can
# talk to the daemon directly — that's why you no longer need `sudo` on
# every `docker` command after this step. Security note: docker-group
# membership is effectively root-equivalent on the host (you can mount
# the host filesystem into a container) — only grant it to trusted users.
sudo usermod -aG docker $USER
 
# Start the Docker daemon.
# On full Ubuntu installs the apt post-install hook auto-starts and
# enables the service, so this is usually a no-op. On lab environments
# (KillerCoda, Instruqt, slim containers) and some VPS images the daemon
# is NOT auto-started — the socket /var/run/docker.sock won't exist
# until you run this. Tested on systemd-based Ubuntu 22.04 / 24.04.
sudo systemctl start docker
sudo systemctl enable docker   # auto-start on boot
 
# Non-systemd hosts: use one of these instead
#   sudo service docker start          # SysV init
#   sudo dockerd > /tmp/dockerd.log 2>&1 &   # last resort, run daemon manually
 
# Pick up the new group membership. Your current shell still uses the
# group list it loaded at login, so docker commands would fail with
# "permission denied" until you do one of:
#   - Close this terminal and open a new one (simplest, works everywhere)
#   - Log out and log back in (for SSH sessions)
#   - Reboot
 
# Verify installation (run this in a NEW terminal after the steps above)
docker run --rm hello-world

Hello from Docker!

# 1. Confirm Buildx CLI plugin is installed
#    (it ships with Docker Engine 23.0+ — the apt install above brought it in)
docker buildx version
# Expected: github.com/docker/buildx v0.12.x linux/amd64
 
# 2. Create a new BuildKit builder instance named "mybuilder"
#    The --use flag immediately sets it as the active builder for all
#    future `docker build` commands in this Docker context.
docker buildx create --name mybuilder --use
 
# 3. Boot the builder so it's ready for the first real build
#    Without --bootstrap, the builder is lazily started on first use,
#    which adds ~5-10 seconds of cold-start to the first build.
#    --bootstrap runs an empty build to warm it up now.
docker buildx inspect --bootstrap

[+] Building 4.2s (1/1) FINISHED

# Install the Docker Scout CLI plugin
# This script downloads the binary and drops it into ~/.docker/cli-plugins/,
# where Docker CLI auto-discovers subcommands. After this, `docker scout`
# becomes available as a regular Docker subcommand.
curl -fsSL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh
 
# Verify the plugin was installed and Docker can find it
docker scout version
# Expected: docker scout version v1.x.x

# Install Node.js via nvm.
# nvm (Node Version Manager) is a shell script that installs Node releases
# into your home directory (~/.nvm) instead of a system path. Two wins:
# (1) global npm installs don't need sudo, (2) you can switch between
# multiple Node versions per project with one command.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
 
nvm install 20          # download and install Node 20 LTS
nvm use 20              # activate it in the current shell
nvm alias default 20    # make it the default for new shells
 
# Verify
node --version   # v20.x.x
npm --version    # 10.x.x

echo "=== Docker ===" && docker --version && \
echo "=== Buildx ===" && docker buildx version && \
echo "=== Compose ===" && docker compose version && \
echo "=== Node ===" && node --version && \
echo "=== npm ===" && npm --version && \
echo "=== Scout ===" && docker scout version 2>/dev/null | head -1 && \
echo "" && echo "All checks passed. Ready to build."

=== Docker ===
Docker version 24.0.7, build afdd53b
=== Buildx ===
github.com/docker/buildx v0.12.1 linux/amd64
=== Compose ===
Docker Compose version v2.24.5
=== Node ===
v20.11.0
=== npm ===
10.2.4
=== Scout ===
docker scout version v1.4.0
 
All checks passed. Ready to build.

mkdir docker-best-practices && cd docker-best-practices
mkdir -p src/routes src/middleware

cat > package.json << 'EOF'
{
  "name": "docker-best-practices",
  "version": "1.0.0",
  "description": "Sample Node.js REST API for Day 2 of 30 Days of DevOps",
  "main": "src/index.js",
  "engines": {
    "node": ">=20.0.0"
  },
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "jest --coverage",
    "test:ci": "jest --ci --forceExit"
  },
  "dependencies": {
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.19.2",
    "helmet": "^7.1.0",
    "morgan": "^1.10.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "nodemon": "^3.1.4",
    "supertest": "^7.0.0"
  }
}
EOF

npm install

du -sh node_modules/
# Roughly ~75 MB — this entire directory should never reach a production image.
# The whole point of the multi-stage Dockerfile in Part 3 is keeping this out.

cat > src/index.js << 'EOF'
'use strict';
 
const express = require('express');
const helmet = require('helmet');
const cors = require('cors');
const morgan = require('morgan');
const { healthRouter } = require('./routes/health');
const { usersRouter } = require('./routes/users');
const { errorHandler } = require('./middleware/errorHandler');
 
const app = express();
const PORT = process.env.PORT || 3000;
 
app.use(helmet());
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || ['http://localhost:3000'],
}));
app.use(morgan(process.env.NODE_ENV === 'production' ? 'combined' : 'dev'));
app.use(express.json({ limit: '10kb' }));
 
app.use('/health', healthRouter);
app.use('/api/users', usersRouter);
 
app.use((req, res) => res.status(404).json({ error: 'Route not found' }));
app.use(errorHandler);
 
const server = app.listen(PORT, '0.0.0.0', () => {
  console.log('Server running on port ' + PORT + ' [' + (process.env.NODE_ENV || 'development') + ']');
});
 
process.on('SIGTERM', () => {
  console.log('SIGTERM received — shutting down gracefully');
  server.close(() => process.exit(0));
});
 
process.on('SIGINT', () => {
  server.close(() => process.exit(0));
});
 
module.exports = { app };
EOF

cat > src/routes/health.js << 'EOF'
'use strict';
 
const { Router } = require('express');
const router = Router();
 
router.get('/', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: Math.floor(process.uptime()),
    environment: process.env.NODE_ENV || 'development',
  });
});
 
router.get('/ready', (req, res) => res.json({ status: 'ready' }));
 
module.exports = { healthRouter: router };
EOF

cat > src/routes/users.js << 'EOF'
'use strict';
 
const { Router } = require('express');
const { z } = require('zod');
 
const router = Router();
 
const UserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'viewer']).default('user'),
});
 
const db = new Map([
  ['1', { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' }],
  ['2', { id: '2', name: 'Bob',   email: 'bob@example.com',   role: 'user'  }],
]);
 
router.get('/', (req, res) => {
  res.json({ users: Array.from(db.values()), total: db.size });
});
 
router.get('/:id', (req, res) => {
  const user = db.get(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});
 
router.post('/', (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({ error: 'Validation failed', details: result.error.flatten() });
  }
  const id = String(Date.now());
  const user = { id, ...result.data };
  db.set(id, user);
  res.status(201).json(user);
});
 
module.exports = { usersRouter: router };
EOF

cat > src/middleware/errorHandler.js << 'EOF'
'use strict';
 
const errorHandler = (err, req, res, next) => {
  const status = err.statusCode || err.status || 500;
  const message = process.env.NODE_ENV === 'production' ? 'An error occurred' : err.message;
 
  console.error({ error: err.message, path: req.path, method: req.method });
  res.status(status).json({ error: message });
};
 
module.exports = { errorHandler };
EOF

cat > .env.example << 'EOF'
NODE_ENV=development
PORT=3000
ALLOWED_ORIGINS=http://localhost:3000
EOF

# Free port 3000 if anything is already on it (safe to re-run this block)
lsof -ti:3000 | xargs kill 2>/dev/null
 
# Start the app in the background, capture its PID
NODE_ENV=development node src/index.js &
APP_PID=$!
 
# Wait up to 5s for /health to respond, then hit it
for i in 1 2 3 4 5; do
  curl -sf http://localhost:3000/health > /dev/null && break
  sleep 1
done
 
# Raw JSON works fine — pretty-printing is optional. If you have `jq`
# installed, pipe through `jq` for a coloured tree view.
curl -s http://localhost:3000/health
echo
 
# Clean up
kill $APP_PID 2>/dev/null
wait $APP_PID 2>/dev/null

{"status":"healthy","timestamp":"...","uptime":0,"environment":"development"}

cat > Dockerfile.naive << 'EOF'
FROM node:20
 
WORKDIR /app
 
COPY . .
 
RUN npm install
 
EXPOSE 3000
 
CMD ["node", "src/index.js"]
EOF

# docker build flags decoded:
#   -f Dockerfile.naive   pick a specific Dockerfile (default is ./Dockerfile)
#   -t myapp:naive        tag the resulting image with name:tag
#   .                     the build context — the directory whose contents
#                         get tar'd up and sent to the Docker daemon.
#                         Everything in .dockerignore is excluded.
docker build -f Dockerfile.naive -t myapp:naive .

[+] Building XXs (8/8) FINISHED
 => [internal] load build definition from Dockerfile.naive
 => [1/4] FROM docker.io/library/node:20
 => [2/4] WORKDIR /app
 => [3/4] COPY . .
 => [4/4] RUN npm install
 => exporting to image

# Image size
docker images myapp:naive --format "Size: {{.Size}}"
# Size: 1.21GB
 
# Is it running as root?
docker run --rm myapp:naive whoami
# root   ← critical security problem
 
# Are devDependencies included?
docker run --rm myapp:naive ls node_modules | grep nodemon
# nodemon   ← dev tools in production
 
# How many system tools are exposed?
docker run --rm myapp:naive which curl bash apt wget
# /usr/bin/curl
# /bin/bash
# /usr/bin/apt
# /usr/bin/wget
# Every one of these is an attacker's tool

cat > Dockerfile << 'EOF'
# ─── Stage 1: deps ────────────────────────────────────────────────────────────
# Install production dependencies only.
# Used by the production stage (COPY --from=deps).
FROM node:20-alpine AS deps
 
WORKDIR /app
 
# Copy lockfiles first — before source code.
# This layer is cached until package.json or package-lock.json changes.
# Changing src/ files won't invalidate this cache layer.
COPY package.json package-lock.json ./
 
# npm ci: uses lockfile exactly, fails if lockfile is out of sync
# --omit=dev: excludes devDependencies (nodemon, jest, etc.)
# --mount=type=cache: BuildKit cache mount on /root/.npm. The npm package
# cache persists between builds, so package tarballs are downloaded once
# and reused across every rebuild — even after `docker system prune -a`.
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev
 
# ─── Stage 2: dev ─────────────────────────────────────────────────────────────
# All dependencies including devDependencies (nodemon, jest, etc.).
# Used by docker-compose.yml for local development with hot reload.
# Tests are NOT run here — that's the test stage's job in CI.
FROM node:20-alpine AS dev
 
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
 
# ─── Stage 3: test ────────────────────────────────────────────────────────────
# Runs tests with all dependencies (including dev).
# CI can build this target to gate on test failures before shipping prod.
FROM node:20-alpine AS test
 
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
 
COPY . .
 
RUN npm run test:ci --if-present
 
# ─── Stage 4: production ──────────────────────────────────────────────────────
# The only stage that ships. Built on distroless — no shell, no package manager,
# no system utilities. The absolute minimum to run a Node.js process.
FROM gcr.io/distroless/nodejs20-debian12 AS production
 
# OCI (Open Container Initiative) image labels — a standardised label
# namespace that registries, scanners, and tools read for provenance and
# discovery. Adding these costs nothing and is a free SEO/auditability win.
LABEL org.opencontainers.image.title="myapp"
LABEL org.opencontainers.image.description="Node.js REST API — 30 Days of DevOps"
LABEL org.opencontainers.image.source="https://github.com/syssignals/30-days-devops"
LABEL org.opencontainers.image.licenses="MIT"
 
WORKDIR /app
 
# Pull only production node_modules from the deps stage.
# Build tools, compilers, and package caches from that stage don't follow.
COPY --from=deps /app/node_modules ./node_modules
 
# Copy application source
COPY src/ ./src/
COPY package.json ./
 
# Distroless images run as nonroot (uid=65532) by default.
# Declaring it explicitly satisfies security scanners and makes intent clear.
USER nonroot
 
# Metadata only — documents that this container listens on 3000.
# Doesn't actually open the port; that still requires `-p 3000:3000` at run time.
EXPOSE 3000
 
# CMD is the script path ONLY — do NOT prefix it with /nodejs/bin/node.
# The distroless nodejs image presets ENTRYPOINT ["/nodejs/bin/node"]
# for you, so this CMD becomes argv for that entrypoint. The final
# command the container actually runs is:
#     /nodejs/bin/node src/index.js
# If you write CMD ["/nodejs/bin/node", "src/index.js"], the container
# tries to run `/nodejs/bin/node /nodejs/bin/node src/index.js` and
# Node fails immediately trying to parse /nodejs/bin/node as JavaScript.
# Exec form (array) also makes node PID 1, so SIGTERM from `docker stop`
# reaches it directly.
CMD ["src/index.js"]
EOF

# --target production: stop at the `production` stage. Other stages (deps,
# dev, test) only run if `production` depends on them via COPY --from=...
# This is what makes multi-stage builds efficient — unrelated stages skip.
# DOCKER_BUILDKIT=1: belt-and-suspenders enabling BuildKit even if the
# active buildx context were reset. Harmless when buildx is already default.
DOCKER_BUILDKIT=1 docker build \
  --target production \
  --tag myapp:production \
  .

[+] Building XXs (13/13) FINISHED
 => [deps 1/3] FROM docker.io/library/node:20-alpine
 => [deps 2/3] COPY package.json package-lock.json ./
 => [deps 3/3] RUN npm ci --omit=dev
 => [production 1/4] COPY --from=deps /app/node_modules
 => [production 2/4] COPY src/ ./src/
 => [production 3/4] COPY package.json ./
 => exporting to image
 => => writing image sha256:<unique-to-your-build>...

docker images | grep myapp

REPOSITORY   TAG          IMAGE ID       CREATED          SIZE
myapp        production   <random hex>   10 seconds ago   ~47 MB
myapp        naive        <random hex>   5 minutes ago    ~1.2 GB

# Start it in the background
docker run -d \
  --name myapp-test \
  -p 3000:3000 \
  -e NODE_ENV=production \
  myapp:production
 
# Wait for the app to come up (give Node ~3 seconds to start listening)
sleep 3
 
# Confirm the container is actually Running (not Restarting / Exited)
docker ps --filter "name=myapp-test" --format "table {{.Names}}\t{{.Status}}"
# NAME         STATUS
# myapp-test   Up 3 seconds
 
# Test the health endpoint from the host
curl -s http://localhost:3000/health | python3 -m json.tool
# {
#     "status": "healthy",
#     ...
# }
 
# Verify the configured user via Docker's own metadata
# (distroless has no `id`/`whoami` binary, so we read what the image
#  config says rather than running a command inside the container)
docker inspect --format '{{.Config.User}}' myapp:production
# nonroot
 
# Verify no shell available — `docker exec sh` SHOULD fail.
# That's the proof the attack surface is reduced. Exit code 126.
docker exec myapp-test sh 2>&1
# OCI runtime exec failed: exec failed: unable to start container process:
# exec: "sh": executable file not found in $PATH: unknown
 
# Same story for `ls`, `cat`, anything you'd reach for in a normal image
docker exec myapp-test ls 2>&1
# OCI runtime exec failed: ... exec: "ls": executable file not found ...
 
# Stop and remove
docker stop myapp-test && docker rm myapp-test

cat > .dockerignore << 'EOF'
# Dependencies — reinstalled inside the image
node_modules/
npm-debug.log*
yarn-debug.log*
 
# Secrets — must never reach an image layer
.env
.env.*
!.env.example
*.pem
*.key
*.p12
*.pfx
.npmrc
 
# Version control
.git/
.gitignore
.gitattributes
 
# IDE and OS artefacts
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db
 
# Test coverage output (regenerated — never needed in an image)
coverage/
.nyc_output/
# NOTE: we deliberately do NOT ignore test files (*.test.js, tests/, __tests__).
# The CI "test" stage in Day 4 builds with `COPY . .` and needs them to run the
# suite. They never reach the production image anyway: the production stage
# copies only `src/`, and our tests live in a top-level `tests/` directory.
 
# Docker config (no need inside the image)
Dockerfile*
docker-compose*.yml
.dockerignore
 
# Documentation
*.md
docs/
 
# CI/CD config
.github/
.gitlab-ci.yml
Jenkinsfile
EOF

# Build with verbose output to see context size
DOCKER_BUILDKIT=1 docker build --progress=plain --target production -t myapp:production . 2>&1 \
  | grep "transferring context"

#1 transferring context: 38.4kB 0.1s done

cat > docker-compose.yml << 'EOF'
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev
    image: myapp:dev
    container_name: myapp-dev
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      # ./src:/app/src:ro  — bind mount with the :ro (read-only) suffix.
      # Your source code on the host is mapped into the container, but
      # the container cannot write back. Hot reload still works (the file
      # WATCH is on the host side), but a compromised container can't
      # modify your code.
      - ./src:/app/src:ro
      # node_modules:/app/node_modules  — named volume (no ./ prefix).
      # Compose syntax: paths starting with ./ or / are bind mounts;
      # bare names refer to named volumes declared in the volumes: section
      # at the bottom of the file. We keep node_modules in a named volume
      # so the Alpine-compiled native modules built INSIDE the container
      # are not clobbered by the macOS/Linux-compiled ones on your host.
      - node_modules:/app/node_modules
    environment:
      NODE_ENV: development
      PORT: 3000
    command: ["node_modules/.bin/nodemon", "--watch", "src", "src/index.js"]
    # healthcheck — Docker runs this command inside the container on a
    # schedule. After enough consecutive failures the container is marked
    # `unhealthy`, which orchestrators (Compose, Swarm, Kubernetes equiv)
    # use to gate traffic and trigger restarts. Fields:
    #   interval     time between checks
    #   timeout      how long the check itself can take before failing
    #   retries      consecutive failures before marking unhealthy
    #   start_period grace window during boot — failures here don't count
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
 
volumes:
  node_modules:
EOF

cat > docker-compose.prod.yml << 'EOF'
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    image: myapp:production
    container_name: myapp-prod
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: 3000
    # read_only: true — make the container's root filesystem read-only.
    # The app cannot create or modify any file outside declared tmpfs and
    # volume mounts. Defeats a huge class of post-exploit techniques that
    # drop a malicious binary or modify config on disk.
    read_only: true
    # tmpfs: - /tmp — mount a RAM-backed temporary filesystem at /tmp.
    # Needed because read_only: true would otherwise block libraries that
    # legitimately need scratch space. tmpfs disappears on container exit
    # (no persistence) so it never accumulates state.
    tmpfs:
      - /tmp
    # security_opt: no-new-privileges:true — sets the kernel's
    # no_new_privs bit, which blocks setuid binaries inside the container
    # from escalating privileges (no setuid root). Defense-in-depth even
    # if the image accidentally includes a setuid binary.
    security_opt:
      - no-new-privileges:true
    # cap_drop: ALL — remove every Linux capability from the container.
    # Capabilities are fine-grained slices of root power (NET_ADMIN,
    # SYS_PTRACE, CHOWN, ...). Dropping them all leaves the process with
    # only what a regular unprivileged user gets. Add back what's needed
    # via `cap_add:` — a Node web server needs nothing.
    cap_drop:
      - ALL
    deploy:
      # limits  = hard caps. Kernel will throttle CPU and OOM-kill the
      #           container if it goes over memory.
      # reservations = soft floor. Scheduler tries to keep these resources
      #                available to the container.
      # Note: under plain `docker compose up` (no Swarm) the deploy block
      # is honoured for resource limits by the modern Compose plugin,
      # but ignored by some older docker-compose binaries. Test if unsure.
      resources:
        limits:
          cpus: '0.50'
          memory: 256M
        reservations:
          cpus: '0.10'
          memory: 64M
EOF

docker compose up --build

[+] Building 19.3s (11/11) FINISHED
[+] Running 2/2
 ✔ Volume "docker-best-practices_node_modules"  Created
 ✔ Container myapp-dev                          Started
myapp-dev  | [nodemon] 3.0.2
myapp-dev  | [nodemon] watching path(s): src/**/*
myapp-dev  | Server running on port 3000 [development]

cat > src/routes/health.js << 'EOF'
'use strict';
 
const { Router } = require('express');
const router = Router();
 
router.get('/', (req, res) => {
  res.json({
    status: 'all-systems-go',
    timestamp: new Date().toISOString(),
    uptime: Math.floor(process.uptime()),
    environment: process.env.NODE_ENV || 'development',
  });
});
 
router.get('/ready', (req, res) => res.json({ status: 'ready' }));
 
module.exports = { healthRouter: router };
EOF

curl -s http://localhost:3000/health | grep status
# {"status":"all-systems-go",...}

cat > src/routes/health.js << 'EOF'
'use strict';
 
const { Router } = require('express');
const router = Router();
 
router.get('/', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: Math.floor(process.uptime()),
    environment: process.env.NODE_ENV || 'development',
  });
});
 
router.get('/ready', (req, res) => res.json({ status: 'ready' }));
 
module.exports = { healthRouter: router };
EOF

docker compose down -v   # -v also removes named volumes

# Naive image — expect many CVEs
echo "=== naive image ===" && \
docker scout cves myapp:naive --only-severity critical,high --format table | head -30
 
echo ""
 
# Production image — expect zero
echo "=== production image ===" && \
docker scout cves myapp:production --only-severity critical,high

=== naive image ===
  CRITICAL CVE-XXXX-XXXXX  curl/libcurl4  ...
  HIGH     CVE-XXXX-XXXXX  openssl        ...
  HIGH     CVE-XXXX-XXXXX  nghttp2        ...
  [output truncated — typically 10-40 high/critical entries depending
   on when you run this and how recently node:20 was last patched]
 
=== production image ===
    ✓ Analyzed image myapp:production
    No critical or high vulnerabilities found
    [occasionally 1-2 highs appear briefly when fresh CVEs are filed
     against the distroless base — re-pull the base in a week to refresh]

docker scout compare myapp:production --to myapp:naive

Comparing myapp:production to myapp:naive
 
Image reference: myapp:production
 
Changes:
  ✓ Critical vulnerabilities:  0  (-3)
  ✓ High vulnerabilities:      0  (-12)
  ✓ Medium vulnerabilities:    0  (-18)
  ✓ Low vulnerabilities:       0  (-14)
  ✓ Image size:                47.2 MB  (-1.17 GB)

mkdir -p docker-template
cp Dockerfile docker-template/
cp .dockerignore docker-template/
cp docker-compose.yml docker-template/
cp docker-compose.prod.yml docker-template/
cp .env.example docker-template/
 
cat > docker-template/bootstrap.sh << 'SCRIPT'
#!/bin/bash
set -euo pipefail
 
APP="${1:-myapp}"
 
echo "Bootstrapping Docker setup for: $APP"
 
# Preflight checks
command -v docker  >/dev/null || { echo "Docker not found"; exit 1; }
docker info &>/dev/null      || { echo "Docker daemon not running"; exit 1; }
 
# Create .env from example if missing
[ ! -f .env ] && [ -f .env.example ] && cp .env.example .env && \
  echo "Created .env from .env.example — update before production use"
 
echo "Building dev image..."
DOCKER_BUILDKIT=1 docker build --target dev --tag "${APP}:dev" .
 
echo "Building production image..."
DOCKER_BUILDKIT=1 docker build --target production --tag "${APP}:production" .
 
echo ""
echo "=== Image sizes ==="
docker images | grep "$APP"
 
echo ""
echo "Ready."
echo "  Development:   docker compose up"
echo "  Production:    docker compose -f docker-compose.prod.yml up"
echo "  Scan:          docker scout cves ${APP}:production"
SCRIPT
 
chmod +x docker-template/bootstrap.sh

npm error missing: express@4.18.2, required by myapp@1.0.0

# Regenerate the lockfile (safe to re-run — guards against missing file)
[ -f package-lock.json ] && rm package-lock.json
npm install
 
# Commit ONLY if this directory is a git repo (this tutorial doesn't
# require it). The guard prevents `fatal: not a git repository` if you
# never ran `git init`.
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && {
  git add package-lock.json
  git commit -m "chore: regenerate package-lock.json"
}
 
# Now rebuild
docker build --target production -t myapp:production .

docker run myapp:production
# Container exits instantly. Run `docker logs <container>` to see why —
# the error tells you which of the two CMD bugs is yours:
#   "exec: \"/bin/sh\": no such file or directory"  → shell-form CMD bug (#1)
#   "SyntaxError: Unexpected token" / "Cannot find module" → double-node CMD bug (#2)

docker inspect --format '{{.Config.Entrypoint}}' gcr.io/distroless/nodejs20-debian12
# [/nodejs/bin/node]

# Pass --version as argv to the preset ENTRYPOINT (which is /nodejs/bin/node).
# Do NOT write `/nodejs/bin/node --version` here — that becomes
# `/nodejs/bin/node /nodejs/bin/node --version` and fails.
docker run --rm gcr.io/distroless/nodejs20-debian12 --version
# v20.x.x

Error: Cannot find module 'express'

[nodemon] watching: src/**/*
# (file changes have no effect)

cat > nodemon.json << 'EOF'
{
  "watch": ["src"],
  "ext": "js,json",
  "legacy-watch": true,
  "delay": 500
}
EOF

docker compose down
docker compose up --build

=> transferring context: 850.00MB

# Confirm .dockerignore exists in the build context directory
ls -la .dockerignore
 
# Check the node_modules line is correct (no trailing space)
grep "node_modules" .dockerignore
# node_modules/
 
# Test: measure context size with a dry run
DOCKER_BUILDKIT=1 docker build --progress=plain --target deps . 2>&1 \
  | grep "transferring context"
# Should show < 100kB

Error response from daemon: permission denied while trying to connect

sudo usermod -aG docker $USER
 
# Your current shell still has its login-time group list, so close this
# terminal and open a new one (or log out and back in for SSH). The new
# shell will read group membership fresh and pick up the docker group.
 
# Verify (in the new terminal)
groups | grep docker
 
# Test
docker scout version

failed to connect to the docker API at unix:///var/run/docker.sock;
check if the path is correct and if the daemon is running:
dial unix /var/run/docker.sock: connect: no such file or directory

# Systemd hosts (Ubuntu 22.04, 24.04 desktop/server, most cloud VMs)
sudo systemctl start docker
sudo systemctl enable docker   # so it auto-starts on next boot
 
# Non-systemd / SysV-init hosts
sudo service docker start
 
# Last resort if neither init system is present (some containers)
sudo dockerd > /tmp/dockerd.log 2>&1 &
 
# Wait 3-5 seconds, then verify the socket exists
ls -l /var/run/docker.sock
 
# Retry
docker run --rm hello-world

docker buildx create --name multibuilder --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target production \
  --tag ghcr.io/syssignals/myapp:latest \
  --push \
  .

cat > Dockerfile << 'EOF'
# ─── Stage 1: deps ────────────────────────────────────────────────────────────
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev
 
# ─── Stage 2: dev ─────────────────────────────────────────────────────────────
FROM node:20-alpine AS dev
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
 
# ─── Stage 3: test ────────────────────────────────────────────────────────────
FROM node:20-alpine AS test
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run test:ci --if-present
 
# ─── Stage 4: production ──────────────────────────────────────────────────────
FROM gcr.io/distroless/nodejs20-debian12 AS production
LABEL org.opencontainers.image.title="myapp"
LABEL org.opencontainers.image.description="Node.js REST API - 30 Days of DevOps"
LABEL org.opencontainers.image.source="https://github.com/syssignals/30-days-devops"
LABEL org.opencontainers.image.licenses="MIT"
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src/ ./src/
COPY package.json ./
USER nonroot
EXPOSE 3000
# Distroless presets ENTRYPOINT ["/nodejs/bin/node"]; CMD is argv for it.
CMD ["src/index.js"]
 
# ─── Stage 5: debug ───────────────────────────────────────────────────────────
# :debug variant of distroless ships busybox so `docker exec ... sh` works
# for investigation. Build with --target debug. NEVER ship this tag to prod.
FROM gcr.io/distroless/nodejs20-debian12:debug AS debug
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src/ ./src/
COPY package.json ./
USER nonroot
CMD ["src/index.js"]
EOF