Docker untuk Node.js: Setup Production-Ready yang Tidak Dibahas Orang | Akousa

dockerfile

# Tahap tunggal: ~600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# Multi-stage: ~150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

Pendekatan	Ukuran Image
`node:20` + `npm install`	1.1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + production deps saja	150 MB
Multi-stage + alpine + deps yang dipangkas	95 MB

dockerfile

# ============================================
# Tahap 1: Instal dependensi
# ============================================
FROM node:20-alpine AS deps
 
# Keamanan: buat direktori kerja sebelum yang lain
WORKDIR /app
 
# Instal dependensi berdasarkan lockfile
# Salin HANYA file package terlebih dahulu — ini penting untuk layer caching
COPY package.json package-lock.json ./
 
# ci lebih baik dari install: lebih cepat, lebih ketat, dan reproducible
# --omit=dev mengecualikan devDependencies dari tahap ini
RUN npm ci --omit=dev
 
# ============================================
# Tahap 2: Build aplikasi
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Salin file package dan instal SEMUA dependensi (termasuk dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# SEKARANG salin kode sumber — perubahan di sini tidak membatalkan cache npm ci
COPY . .
 
# Build aplikasi (kompilasi TypeScript, Next.js build, dll.)
RUN npm run build
 
# ============================================
# Tahap 3: Runner produksi
# ============================================
FROM node:20-alpine AS runner
 
# Tambahkan label untuk metadata image
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Keamanan: instal dumb-init untuk penanganan sinyal PID 1 yang benar
RUN apk add --no-cache dumb-init
 
# Keamanan: atur NODE_ENV sebelum yang lain
ENV NODE_ENV=production
 
# Keamanan: gunakan pengguna non-root
# Image node sudah menyertakan pengguna 'node' (uid 1000)
USER node
 
# Buat direktori app yang dimiliki pengguna node
WORKDIR /app
 
# Salin dependensi produksi dari tahap deps
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Salin aplikasi yang sudah di-build dari tahap builder
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Expose port (hanya dokumentasi — tidak mempublikasikannya)
EXPOSE 3000
 
# Health check: curl tidak tersedia di alpine, gunakan node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# Gunakan dumb-init sebagai PID 1 untuk menangani sinyal dengan benar
ENTRYPOINT ["dumb-init", "--"]
 
# Jalankan aplikasi
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("SIGTERM diterima, shutdown dengan anggun");
  server.close(() => {
    console.log("Server HTTP ditutup");
    // Tutup koneksi database, flush log, dll.
    process.exit(0);
  });
});

# .dockerignore
node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile
docker-compose*.yml
.dockerignore
README.md
LICENSE
.github
.vscode
.idea
coverage
.nyc_output
*.test.ts
*.test.js
*.spec.ts
*.spec.js
__tests__
test
tests
docs
.husky
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
vitest.config.*

dockerfile

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# Mount secret saat build — tidak pernah disimpan di image
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml (mode Swarm)
version: "3.8"
services:
  api:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
 
secrets:
  db_password:
    external: true
  api_key:
    external: true

javascript

import { readFileSync } from "fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // Fallback ke environment variable untuk pengembangan lokal
    return process.env[name.toUpperCase()];
  }
}
 
const dbPassword = getSecret("db_password");

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

javascript

// healthcheck.js
const http = require("http");
 
const options = {
  hostname: "localhost",
  port: 3000,
  path: "/health",
  timeout: 5000,
};
 
const req = http.request(options, (res) => {
  process.exit(res.statusCode === 200 ? 0 : 1);
});
 
req.on("error", () => process.exit(1));
req.on("timeout", () => {
  req.destroy();
  process.exit(1);
});
 
req.end();

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // Periksa koneksi database
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Periksa koneksi Redis
    await redis.ping();
    checks.redis = "connected";
  } catch (err) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        NODE_VERSION: "20"
    ports:
      - "3000:3000"
      - "9229:9229" # Debugger Node.js
    volumes:
      # Mount kode sumber untuk hot reload
      - .:/app
      # Volume anonim untuk mempertahankan node_modules dari image
      # Ini mencegah node_modules host menimpa node_modules container
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:devpassword@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev
 
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: devpassword
    volumes:
      # Volume bernama untuk data persisten antar restart container
      - pgdata:/var/lib/postgresql/data
      # Skrip inisialisasi
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    command: redis-server --appendonly yes
 
  # Opsional: UI admin database
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
 
volumes:
  pgdata:
  redisdata:

dockerfile

# Dockerfile.dev
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
WORKDIR /app
 
# Instal semua dependensi (termasuk devDependencies)
COPY package*.json ./
RUN npm ci
 
# Kode sumber di-mount melalui volume, tidak disalin
# Tapi tetap perlu untuk build awal
COPY . .
 
EXPOSE 3000 9229
 
CMD ["npm", "run", "dev"]

yaml

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/yourorg/myapp:${TAG:-latest}
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
      replicas: 2
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - internal
      - web
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --appendonly yes
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "3"
 
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local
 
networks:
  internal:
    driver: bridge
  web:
    external: true

dockerfile

# ============================================
# Tahap 1: Instal dependensi
# ============================================
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
# ============================================
# Tahap 2: Build aplikasi
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Nonaktifkan telemetri Next.js saat build
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# Tahap 3: Runner produksi
# ============================================
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN apk add --no-cache dumb-init
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# Pengguna non-root
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Salin aset publik
COPY --from=builder /app/public ./public
 
# Siapkan direktori output standalone
# Secara otomatis memanfaatkan output traces untuk mengurangi ukuran image
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Salin server standalone dan file statis
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "server.js"]

myapp:latest (alpine 3.19.1)
=============================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Node.js (node_modules/package-lock.json)
=========================================
Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

┌──────────────┬────────────────┬──────────┬────────┬───────────────┐
│   Library    │ Vulnerability  │ Severity │ Status │ Fixed Version │
├──────────────┼────────────────┼──────────┼────────┼───────────────┤
│ semver       │ CVE-2022-25883 │ HIGH     │ fixed  │ 7.5.4         │
│ word-wrap    │ CVE-2023-26115 │ MEDIUM   │ fixed  │ 1.2.4         │
└──────────────┴────────────────┴──────────┴────────┴───────────────┘

yaml

# .github/workflows/docker.yml
- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
 
- name: Scan image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    exit-code: 1
    severity: CRITICAL,HIGH
    ignore-unfixed: true

yaml

# .github/workflows/docker.yml
name: Build and Push Docker Image
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      security-events: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          exit-code: 1
          severity: CRITICAL,HIGH
          ignore-unfixed: true
 
      - name: Upload Trivy results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

dockerfile

# Konfigurasi build-time
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# Konfigurasi runtime
ENV PORT=3000
 
# SALAH: Ini membuat secret terlihat di image
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# BENAR: Berikan secret saat runtime
# docker run -e API_KEY=secret myapp

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - internal
 
  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    networks:
      - internal
 
volumes:
  prometheus_data:
  grafana_data:

javascript

import { collectDefaultMetrics, Registry, Histogram } from "prom-client";
 
const register = new Registry();
collectDefaultMetrics({ register });
 
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Durasi request HTTP dalam detik",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [register],
});
 
// Middleware
app.use((req, res, next) => {
  const end = httpRequestDuration.startTimer();
  res.on("finish", () => {
    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
  });
  next();
});
 
// Endpoint metrik
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Pendekatan	Ukuran Image
`node:20` + `node_modules` lengkap + `.next`	1.4 GB
`node:20-alpine` + `node_modules` lengkap + `.next`	600 MB
`node:20-alpine` + output standalone	120 MB

Mengapa Dockerfile Anda Saat Ini Mungkin Salah

Berjalan sebagai Root

Menginstal devDependencies di Produksi

COPY Semua

Tanpa Health Checks

Tanpa Strategi Layer Caching

Multi-Stage Builds: Keuntungan Terbesar

Perbandingan Ukuran Nyata

Mengapa Alpine?

Dockerfile Produksi Lengkap

Mengapa Tiga Tahap Alih-alih Dua?

Mengapa dumb-init?

File .dockerignore

Layer Caching: Berhenti Menunggu 3 Menit Per Build

Urutan yang Salah

Urutan yang Benar

Cache Mount untuk npm

Menggunakan ARG untuk Cache Busting

Manajemen Secrets: Berhenti Meletakkan Secrets di Dockerfile

Tiga Level Secrets

File .env dan Docker

Health Checks: Beri Tahu Docker Bahwa Aplikasi Anda Benar-benar Berjalan

Instruksi HEALTHCHECK

Mengapa Tidak Menggunakan curl?

Endpoint Health

Mengapa Health Checks Penting untuk Orchestrator

docker-compose untuk Pengembangan

Pola Pengembangan Utama

Dockerfile Pengembangan

Docker Compose Produksi

Apa yang Berbeda dari Pengembangan

Khusus Next.js: Output Standalone

Dockerfile Produksi Next.js

Perbandingan Ukuran untuk Next.js

Penanganan File Statis

Sharp untuk Optimasi Gambar

Pemindaian Image dan Keamanan

Trivy: Pindai Image Anda

Filesystem Read-Only

Hapus Semua Capabilities

Pin Digest Base Image Anda

Integrasi CI/CD: Menyatukan Semuanya

BuildKit Cache di CI

Jebakan Umum dan Cara Menghindarinya

Konflik node_modules di dalam Image vs Host

Penanganan SIGTERM di Proyek TypeScript

Batas Memori dan Node.js

Masalah Timezone

Build Arguments vs Environment Variables

Monitoring di Produksi

Daftar Periksa

Artikel Terkait

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy