DEV Community: FOLASAYO SAMUEL OLAYEMI

Quick system design question: Do you actually know the structural difference between a Reverse Proxy, a Load Balancer, and an API Gateway? (Hint: They aren't the same thing!).

FOLASAYO SAMUEL OLAYEMI — Mon, 13 Jul 2026 11:08:23 +0000

FOLASAYO SAMUEL OLAYEMI

Jul 13

Reverse Proxy vs Load Balancer vs API Gateway: The Real Difference

#systemdesign #tutorial #api #architecture

7 min read

Reverse Proxy vs Load Balancer vs API Gateway: The Real Difference

FOLASAYO SAMUEL OLAYEMI — Mon, 13 Jul 2026 11:06:37 +0000

Imagine you have built a backend server that handles requests perfectly in development. It easily survives a few hundred users. Then, your application gets picked up on social media, and suddenly 10,000 requests hit your server at the exact same second.

Connections pile up, requests time out, CPU usage spikes, and users are stuck staring at loading screens or a dreaded 502 Bad Gateway error.

Most engineers know the obvious fix: add more servers or put something in front of the backend. But what exactly goes in front? The moment you enter the realm of system design, you hear three terms used interchangeably: Reverse Proxy, Load Balancer, and API Gateway. Even experienced engineers mix them up because they all sit between users and servers. However, they exist for completely different reasons, protect against different failures, and solve distinct scaling problems.

1. The Starting Point: Direct Connection (Layer 0)

In the simplest version of the web, a client sends a request directly to a backend server, and the server sends back a response. This works fine until your production environment starts taking heavy traffic.

When a server sits directly on the public internet, it must handle everything itself:

TLS/SSL Encryption: Every HTTPS request begins with a TLS handshake, which requires expensive cryptographic calculations.
Static Files & Business Logic: The server must fetch database records, compress responses, and serve static images simultaneously.
Security Risks: The server's IP address is entirely public in DNS records. Anyone can scan it, probe it, or launch a direct attack.

It is like asking a surgeon to perform complex surgery while simultaneously managing patient intake, sterilizing equipment, answering phone calls, and handling billing. Eventually, the core surgery suffers.

2. The Protective Buffer: Reverse Proxy

To fix the vulnerabilities of a direct connection, engineers introduce a protective layer at the edge of the internet: the Reverse Proxy.

Forward Proxy vs. Reverse Proxy

Forward Proxy (Client-Side): Works on behalf of the client. Examples include VPNs or IP-masking tools. They sit in front of a user to hide their identity from the server.
Reverse Proxy (Server-Side): Works on behalf of the server. It sits in front of the backend infrastructure. Clients talk to the proxy's address, and the proxy decides where to route the request.

[ Clients ]  ───>  [ Reverse Proxy ]  ───(Trusted Private Network)───>  [ Backend Server ]

Core Responsibilities of a Reverse Proxy

By placing a tool like Nginx, HAProxy, Caddy, or Envoy in front of your backend, you can offload heavy infrastructure tasks:

SSL Termination: The proxy handles the CPU-heavy cryptographic work of TLS handshakes at the edge. It then passes plain HTTP to the backend over a trusted, private internal network.
Caching: If an API returns the same product catalog to 1,000 users, the proxy saves the first response in memory. The next 999 requests are served instantly from the cache without waking up the backend.
Compression: The proxy compresses payloads using algorithms like Gzip or Brotli before they leave, lowering bandwidth usage and reducing backend CPU strain.
Anonymity & Security: Your application server's IP address stays hidden. You can handle rate limiting, header enforcement, and block malicious patterns right at the proxy layer.

The Key Insight: A reverse proxy is general purpose. It operates primarily at the connection and routing level. It does not understand business logic, user authentication, permissions, or API versions; it simply forwards traffic based on static routing rules.

3. Scaling Horizontally: The Load Balancer

Even with a reverse proxy handling SSL and caching, a single backend server has physical limits on CPU, memory, and concurrent network connections. When traffic triples, you must scale horizontally by adding more servers (e.g., Server A, Server B, Server C).

This introduces new structural problems: How do you distribute traffic evenly? What happens if one server crashes?

A Load Balancer is essentially a reverse proxy that has evolved one highly specialized skill: intelligent traffic distribution. It tracks server health and decides exactly where to send each incoming request.

Traffic Distribution Strategies

Round Robin: Passes requests sequentially (Server A -> Server B -> Server C -> repeat). It works best when all servers have equal hardware specifications and requests require similar processing power.
Least Connections: Tracks which backend server is currently handling the fewest active requests and shifts traffic there. This is ideal for systems where some requests trigger heavy database queries while others finish instantly.
Weighted Round Robin: Assigns capacity scores based on hardware capability. A robust 64GB RAM machine will intentionally receive significantly more traffic than a smaller 16GB instance.
IP Hashing: Uses the client's IP address to consistently route them to the same backend server. This is occasionally used for session affinity, though modern distributed systems prefer stateless architectures.

Layer 4 vs. Layer 7 Load Balancing

Load balancers operate at different layers of the Open Systems Interconnection (OSI) model:

Attribute	Layer 4 (Transport Level)	Layer 7 (Application Level)
Data Scope	Understands TCP connections, IP addresses, and ports. Blind to HTTP data.	Inspects full HTTP traffic, including URLs, headers, and cookies.
Performance	Incredibly fast and memory efficient; handles raw packet streams.	Slightly higher processing overhead due to parsing HTTP payloads.
Routing Ability	Can only route to a target pool based on IP/Port data.	Can route `/api/users` to one cluster and `/payments` to a highly secure cluster.
AWS Analogue	Network Load Balancer (NLB)	Application Load Balancer (ALB)

High Availability through Health Checks

The defining feature of a load balancer is Health Checking. It continuously pings backend servers to confirm they are alive. If a server crashes, the load balancer immediately pulls it out of the rotation pool. Traffic is automatically rerouted to healthy machines without any human intervention, preventing system downtime.

4. Decoupling Microservices: The API Gateway

As your application grows, monolithic codebases often become risky to deploy. To solve this, engineering teams split the system into microservices (e.g., a User service, Order service, Payment service, and Notification service).

While this allows individual teams to build and deploy independently, it creates duplicate infrastructure problems. Suddenly, every microservice needs its own code to:

Validate JWTs, check user permissions, and verify API keys.
Implement rate-limiting to prevent traffic abuse.
Track latency, log errors, and expose metrics consistently.

If every team implements these features independently, you end up with 12 separate copies of infrastructure logic that gradually drift apart, creating security vulnerabilities and code maintenance headaches.

An API Gateway solves this by acting as a reverse proxy that actually understands your APIs. It serves as a unified entry point that orchestrates cross-cutting concerns at the edge before requests hit your services.

[ Client ] ──> [ API Gateway ] ──┬──> [ User Service Pool ]
                                 ├──> [ Order Service Pool ]
                                 └──> [ Payment Service Pool ]

Advanced Features of an API Gateway

Centralized Authentication: The gateway validates tokens once at the perimeter. Malformed or unauthenticated requests are rejected immediately, freeing backend services to focus entirely on core business logic.
Advanced Rate Limiting & Quotas: Tiered limits can be applied centrally. For example, free-tier accounts might be limited to 100 requests per minute, while enterprise users get 10,000, managed outside the application code.
Request & Response Transformation: The gateway can translate data formats on the fly, such as converting a modern mobile client's JSON request into an older legacy service's expected XML payload.
API Versioning & Blue/Green Migrations: You can gracefully migrate from /v1 to /v2 APIs at the gateway layer. The gateway silently routes /v1 requests to legacy servers while seamlessly directing newer clients to updated microservices.
Unified Observability: Since all traffic traverses a single point, the gateway offers a complete architectural view of error rates, traffic spikes, and localized latency issues.

Popular dedicated API Gateway tools include Kong, AWS API Gateway, Apigee, and Tyke.

5. Why the Terms Blur: The Feature Spectrum

Engineers frequently mix these terms up because modern software tools do not strictly respect theoretical boundaries. The tools often wear multiple hats depending on how they are configured.

Nginx: Began as a reverse proxy. However, by adding an upstream block, it transforms into a load balancer. By adding Lua plugins or OpenResty extensions, it can handle JWT validation and rate limiting, functioning as an API gateway.
Kong: Marketed as an API gateway, but it is built directly on top of Nginx. It relies internally on reverse proxy mechanics and load balancing algorithms to fulfill its gateway duties.
Cloud Services: AWS offers both an Application Load Balancer (ALB) and an API Gateway. While conceptually separate, they overlap; an ALB can handle content-based path routing, and an API Gateway natively distributes traffic across server pools.

Instead of thinking of these as isolated product categories, view them as a spectrum of capabilities:

[ Reverse Proxy ] ───────────────> [ Load Balancer ] ────────────────> [ API Gateway ]
  - SSL Termination                  - Traffic Distribution            - Auth & Permissions
  - Content Caching                  - Server Health Checks            - Tiered Rate Limiting
  - Payload Compression              - Horizontal Scaling              - API Versioning
  - IP Masking                       - Failover Routing                - Data Transformation

6. How They Layer Together in Production

In production systems serving millions of users, you rarely choose just one tool. Instead, you layer them sequentially because they solve entirely different problems.

Here is what happens when a user triggers a dynamic request inside an enterprise application:

[ User ] 
   │
   ▼
[ Content Delivery Network (CDN) ]  <-- Global Edge Reverse Proxy (Caches static files/SSL)
   │ (Cache Miss / Dynamic Request)
   ▼
[ API Gateway ]                     <-- Evaluates Auth, Rate Limits, and API Routing
   │ (e.g., Path: /api/payments)
   ▼
[ Service Load Balancer ]           <-- Balances traffic across the Payment cluster
   │ (Chooses healthiest node)
   ▼
[ Service Instance (Proxy + App) ]  <-- Internal Envoy/Nginx proxy handles local TLS/compression

The CDN Layer: The request first hits a CDN (like Cloudflare or Fastly), which functions as a globally distributed network of reverse proxies. It serves static assets locally and terminates SSL close to the user.
The API Gateway Layer: Dynamic requests pass through to the origin infrastructure's API Gateway. The gateway checks API keys, confirms rate limits, verifies authentication, and handles routing.
The Cluster Load Balancer: The gateway passes the request to the specific service pool (e.g., the Payment Service). A dedicated load balancer sits in front of that service to distribute the request to one of several running instances.
The Local Service Proxy: Even inside the server instance, a lightweight reverse proxy (like Envoy or Nginx) might run alongside the code to compress responses or manage secure internal service-to-service mesh communications.

Summary Checklist: Which One Do You Need?

Choose a Reverse Proxy (e.g., Nginx, Caddy) if you have a single backend server and need basic security, SSL termination, payload compression, or static content caching.
Choose a Load Balancer (e.g., HAProxy, AWS ALB) if your traffic has outgrown a single machine and you need to scale horizontally across multiple identical backend servers with automated health checks.
Choose an API Gateway (e.g., Kong, Tyke) if you are managing complex public APIs or microservices that require central management for authentication, versioning, data transformations, and billing tiers.

Setting Up a Production CI/CD Pipeline for a Python/Django App

FOLASAYO SAMUEL OLAYEMI — Mon, 13 Jul 2026 08:38:07 +0000

A practical walkthrough of building a complete GitHub Actions pipeline for a Django project, from a multi-stage Dockerfile through vulnerability scanning to zero-downtime deploys via SSH. This is the exact four-job pattern I now use across every Python service I ship, adapted from the same standard I run for Node/React projects.

The end state: push to develop, and within a few minutes you have a scanned, versioned image running on your server, with your database and cache layers never touched by the automation.

The Shape of the Pipeline

Four jobs, each gating the next:

Dependency check: fail fast on known-vulnerable packages before you spend CI minutes building
Build & push: compile the image once, tag it with the exact commit SHA, push to GHCR
Image scan: Trivy scans the built image for OS and package CVEs
Deploy: SSH into the server, pull the exact scanned tag, restart only the application containers

Each job only runs if the previous one succeeds. Nothing reaches production without passing every gate.

Step 1: The Dockerfile

Python images benefit enormously from a multi-stage build, because compiling native extensions (psycopg2, Pillow, lxml, and friends) needs a full build toolchain that has no business existing in your production image.

# =========================
# 1. Base Stage
# Shared env/config for both builder and runtime, kept DRY
# so these settings can't drift out of sync between stages.
# =========================
FROM python:3.9-slim-bookworm AS base
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# =========================
# 2. Builder Stage
# Compiles wheels for all deps requiring native extensions
# so the runtime image doesn't need a full build toolchain.
# =========================
FROM base AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential gcc g++ make pkg-config \
    libpq-dev libffi-dev libmagic-dev libssl-dev zlib1g-dev \
    libjpeg-dev libxml2-dev libxslt1-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements ./requirements
RUN python -m pip install --upgrade pip setuptools wheel
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements/prod.txt

# =========================
# 3. Runtime Stage
# Only the shared libs the compiled wheels actually need.
# no compilers, no -dev headers.
# =========================
FROM base AS runtime

RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 libmagic1 libjpeg62-turbo libxml2 libxslt1.1 netcat-openbsd \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /wheels /wheels
COPY requirements/prod.txt ./requirements/prod.txt
RUN pip install --no-cache-dir --no-index --find-links=/wheels -r requirements/prod.txt \
    && rm -rf /wheels requirements

COPY docker/prod/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
COPY . .

RUN addgroup --system --gid 1001 django \
    && adduser --system --uid 1001 --gid 1001 django \
    && chown -R django:django /app
USER django

EXPOSE 8000
ENTRYPOINT ["/entrypoint.sh"]
CMD ["gunicorn", "core.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "3"]

A few decisions worth explaining:

Why a shared base stage? Both builder and runtime need the same WORKDIR and ENV settings. Declaring them twice means they can silently drift apart. One base stage, two things extending it. Same idea as a shared config file.

Why --no-index --find-links=/wheels instead of just pip install -r requirements? The runtime stage never touches the internet or a package index. It installs only the exact wheels the builder already compiled. This makes builds reproducible and avoids the runtime stage accidentally pulling in a different resolved version than what was actually tested.

Why a non-root user? Running as django (uid 1001) rather than root limits blast radius if the container is ever compromised. chown -R on the app directory before switching users is required, or the process won't have permission to write anything (log files, temp files, etc.).

Never bake runserver into a production image. Django's development server isn't built for concurrent connections or production traffic. Gunicorn, already installed via requirements/prod.txt in most Django boilerplates, is the standard WSGI server for this.

Step 2: A Real Entrypoint

The entrypoint's only jobs: wait for the database to be reachable, apply already-committed migrations, then hand off to whatever command the container was actually started with.

#!/bin/sh
set -e

if [ "$DATABASE" = "postgres" ]; then
  echo "Waiting for PostgreSQL at $SQL_HOST:$SQL_PORT..."
  while ! nc -z "$SQL_HOST" "$SQL_PORT"; do
    sleep 0.1
  done
  echo "PostgreSQL is up."
fi

python manage.py migrate --no-input

exec "$@"

Two things to get right here, because both are easy to get subtly wrong:

set -e so the script stops on the first failure instead of limping forward.
exec "$@" at the end, not just "$@". Without exec, your app runs as a child process of the shell script, which means it never receives signals like SIGTERM directly, and Docker's graceful shutdown won't work correctly.

Notably absent: makemigrations. That command should only ever run in development. Auto-generating schema changes at deploy time means production can apply migrations nobody reviewed. Migrations get written and committed in dev; production only ever runs migrate.

Step 3: The GitHub Actions Workflow

name: Deploy My Django App

on:
  workflow_run:
    workflows: ["CodeQuality Checks"]
    types:
      - completed
    branches:
      - develop

env:
  REGISTRY: ghcr.io

concurrency:
  group: deploy-my-django-app
  cancel-in-progress: false

jobs:
  dependency-check:
    name: Dependency Vulnerability Check
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - uses: actions/setup-python@v5
        with:
          python-version: '3.9'
      - run: pip install pip-audit
      - run: pip-audit -r requirements/prod.txt
        continue-on-error: true

Why pip-audit -r requirements/prod.txt instead of installing everything first? pip-audit can scan a requirements file directly against known vulnerability databases without needing a full working install. Faster, and it doesn't require your build toolchain just to run a security check.

Why workflow_run instead of triggering directly on push? This chains the deploy pipeline behind a separate code-quality workflow (linting, tests); deploy only fires if that already succeeded. if: ${{ github.event.workflow_run.conclusion == 'success' }} is the gate that enforces it.

  build-and-push:
    name: Build & Push Image
    needs: dependency-check
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
      packages: write
    outputs:
      image: ${{ steps.image-name.outputs.image }}
      tag: sha-${{ github.event.workflow_run.head_sha }}
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - name: Set lowercase image name
        id: image-name
        run: |
          echo "image=ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ steps.image-name.outputs.image }}
          tags: |
            type=sha,prefix=sha-
            type=raw,value=latest,enable={{is_default_branch}}
      - uses: docker/build-push-action@v7
        with:
          context: .
          file: ./docker/prod/Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

The single most important line in this whole pipeline:

tag: sha-${{ github.event.workflow_run.head_sha }}

This gets exposed as a job output and threaded through every job after it. The alternative, assuming a :latest tag exists and using it everywhere, silently breaks the moment your trigger branch isn't your repo's actual GitHub-configured default branch, because docker/metadata-action's enable={{is_default_branch}} only tags latest on the real default branch. Deploying by SHA means you always know exactly what commit is running in production, and rollbacks become "redeploy this specific tag" instead of guesswork.

GitHub Actions cache (cache-from/cache-to: type=gha) persists Docker layer cache between runs. Your dependency-install layer won't rebuild from scratch every single push unless requirements/prod.txt actually changed.

  image-scan:
    name: Container Security Scan
    needs: build-and-push
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      packages: read
    steps:
      - uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ needs.build-and-push.outputs.image }}:${{ needs.build-and-push.outputs.tag }}
          severity: CRITICAL,HIGH
          exit-code: '1'
          ignore-unfixed: true

exit-code: '1' is what makes this a real gate rather than a report nobody reads. The job fails, the pipeline stops, nothing gets deployed. ignore-unfixed: true filters out CVEs with no available patch yet, since failing a build over something you can't currently fix just trains everyone to ignore the scanner.

If this catches something, don't assume it's your application code. Base OS images (python:3.9-slim-bookworm here) accumulate CVEs in their bundled packages over time too. A quick apk update && apk upgrade --no-cache (Alpine) or apt-get update && apt-get upgrade -y (Debian-based) at the top of your runtime stage often clears these without touching a single line of application code.

  deploy:
    name: Deploy to Server
    runs-on: ubuntu-latest
    needs: [build-and-push, image-scan]
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - uses: appleboy/ssh-action@v1.2.5
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          script: |
            echo "${{ secrets.GHCR_PAT }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
            docker pull ${{ needs.build-and-push.outputs.image }}:${{ needs.build-and-push.outputs.tag }}
            cd /home/apps/my-django-app
            IMAGE_TAG=${{ needs.build-and-push.outputs.tag }} docker compose -f docker-compose.prod.yml up -d --no-deps api celery celery-beat
            docker image prune -f

The line that matters most for anything with a database:

docker compose ... up -d --no-deps api celery celery-beat

--no-deps, plus explicitly naming only the application services, means your database and cache containers are never included in the recreate. Compare that to a blanket docker compose down && docker compose up -d, which tears down and recreates every service in the file, including your database, on every single deploy. One flag is the difference between "safe to deploy fifty times a day" and "one bad merge away from an outage."

Step 4: The Production Compose File

version: "3.7"

services:
  api: &api
    image: ghcr.io/your-org/your-app:${IMAGE_TAG:-latest}
    container_name: my-app-api
    restart: unless-stopped
    command: gunicorn core.wsgi:application --bind 0.0.0.0:8000 --workers 3
    env_file:
      - ./.env
    ports:
      - "8005:8000"
    depends_on:
      - redis
      - db

  celery:
    <<: *api
    container_name: my-app-celery
    command: celery worker --app=core --loglevel=info
    ports: []
    depends_on:
      - redis
      - api

  db:
    image: postgres:12.1-alpine
    container_name: my-app-db
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    env_file:
      - ./.env

  redis:
    image: redis:alpine
    container_name: my-app-redis
    restart: unless-stopped

volumes:
  postgres_data:

The &api / <<: *api YAML anchor pattern means celery inherits everything from api (image, env file, restart policy) and only overrides what's different: the command and port mapping. One image built once, run with different startup commands for the web process versus the background worker.

${IMAGE_TAG:-latest} reads the IMAGE_TAG environment variable the deploy step sets, falling back to latest if it's ever run manually without that variable set, useful for local debugging on the server without breaking the syntax.

Step 5: Verify Before You Trust It

Before pointing real traffic at this, worth confirming:

# Does the volume actually persist across recreations of the app containers?
docker volume ls | grep postgres_data

# Does the entrypoint's DB wait-loop actually see the right env vars?
docker exec -it my-app-api env | grep -E "DATABASE|SQL_HOST|SQL_PORT"

# Does a manual run of the compose file work before letting CI do it automatically?
docker compose -f docker-compose.prod.yml up -d --no-deps api celery celery-beat
docker compose -f docker-compose.prod.yml logs -f api

Required secrets in your repo settings: SERVER_IP, SERVER_USER, SERVER_SSH_KEY, GHCR_PAT (a personal access token with read:packages, used for the server to authenticate against GHCR independently of whatever's cached in CI).

Why This Shape, Specifically

Every piece of this pipeline exists because of a failure mode it closes off:

Dependency check before build: don't spend CI minutes building an image from packages you already know are vulnerable.
SHA-based tags instead of latest: always know exactly what's running; rollbacks become trivial.
Image scan after build, before deploy: you're scanning what will actually run, not just source code.
--no-deps on deploy: stateful services are structurally protected from an automation mistake, not just protected by convention.
Non-root runtime user: limits what an exploited container can actually do.
Multi-stage Dockerfile: smaller final image, no build toolchain shipped to production, faster pulls.

None of these individually are complicated. Together, they're the difference between a deploy you have to babysit and one you can trust to run unattended, multiple times a day, without holding your breath.

Debugging a Legacy CRA + Django Deployment Pipeline: A DevOps Postmortem

FOLASAYO SAMUEL OLAYEMI — Sun, 12 Jul 2026 19:20:24 +0000

A few weeks ago I was handed two deployment tasks that looked routine on paper: containerize and ship a React frontend, then do the same for its Django backend. Both apps were already running somewhere one on manage.py runserver, the other via a dev Dockerfile nobody had touched in years. "Just make it production-ready" is a deceptively small sentence. Here's what actually happened.

Part 1: The Frontend That Wasn't Next.js

The first Dockerfile I inherited looked like this at the runner stage:

FROM node:22-alpine AS runner
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
CMD ["node", "server.js"]

Clean multi-stage build, sensible layer caching, non-root-adjacent structure. One problem: the project was create-react-app via craco, not Next.js. .next/standalone doesn't exist in a CRA build there's no server to run. This was almost certainly a copy-paste from a Next.js project's Dockerfile that nobody adapted. The build would fail outright the moment it reached that COPY step.

Lesson one: before touching a Dockerfile, check what the build script actually produces. "build": "craco build" outputs a static build/ directory. No amount of Dockerfile cleverness fixes a mismatched deployment model you have to match the artifact, which meant swapping the runner stage entirely to an nginx static file server instead of a Node process.

The Node version trap

With the runner fixed, the next failure was a native module rebuild:

error Command "rebuild" not found.

The Dockerfile had yarn install --frozen-lockfile --ignore-scripts followed by yarn rebuild esbuild sharp except rebuild isn't a Yarn Classic command, it's an npm one. Someone had disabled install scripts (probably for build speed or a supply-chain concern) and then tried to manually force native binaries to compile, using syntax from the wrong package manager entirely.

The fix was almost too simple: drop --ignore-scripts, let yarn install run postinstall naturally, and delete the broken rebuild line. But underneath that surface bug was a nastier one the deps stage was building on node:24-alpine while builder/runner ran node:22-alpine. Native modules like sharp and esbuild compile against a specific Node ABI. Compile on 24, run on 22, and you risk a runtime crash that CI won't catch it only shows up when the container actually starts. Two completely different Node majors across stages had been quietly coexisting because --ignore-scripts was skipping the native compile step that would have caught the mismatch immediately.

Lesson two: every FROM node:X-alpine in a multi-stage build should agree on X, unless you have a very specific reason otherwise. Silent ABI mismatches are the kind of bug that passes CI and fails in production.

OpenSSL, then postcss, then Node itself

Once the build actually reached yarn build, it hit:

Error: error:0308010C:digital envelope routines::unsupported

react-scripts@4.0.3 bundles Webpack 4, which uses Node's legacy MD4 hashing internals removed by default once Node moved to OpenSSL 3 (Node 17+). The standard fix, NODE_OPTIONS=--openssl-legacy-provider, cleared that one.

Then a second, unrelated error surfaced:

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/tokenize' is not defined by "exports"

This one traced to postcss-safe-parser, a transitive dependency of react-scripts@4's CSS minification chain, which ships its own nested, ancient copy of postcss. That old postcss's package.json never declared a wildcard exports field. Node 17+ enforces exports strictly and hard-errors on any path not explicitly declared. Node 16 only warned. Node 24 refused outright.

I initially reached for the obvious fix downgrade the build stage to Node 16, the last version before this became a hard error. It worked, but it was the wrong call to standardize on, and I was right to get pushback on it. Node 16 is EOL; picking it just because it dodges a rule isn't a fix, it's postponing the problem. The better answer, once I thought about who actually owns what: this is application dependency debt, not infrastructure. The real fix is a yarn.lock change a developer should make pinning the nested postcss via resolutions. But as the DevOps engineer, pulling the repo and editing package.json myself wasn't really my lane either.

The answer that stuck: patch the broken nested package.json from inside the Dockerfile itself, after yarn install, using a small inline Node script:

RUN node -e " \
  const fs = require('fs'); \
  const path = 'node_modules/postcss-safe-parser/node_modules/postcss/package.json'; \
  if (fs.existsSync(path)) { \
    const pkg = JSON.parse(fs.readFileSync(path)); \
    pkg.exports = pkg.exports || {}; \
    pkg.exports['./lib/*'] = './lib/*.js'; \
    fs.writeFileSync(path, JSON.stringify(pkg, null, 2)); \
  }"

No lockfile change, no dev involvement, Node stays on 24 across the fleet. It's explicitly a stopgap if the dependency tree shifts and postcss-safe-parser nests its postcss copy somewhere else, this silently stops applying and the original error resurfaces. That's a feature, not a bug: it fails loud and traceable rather than papering over a moving target indefinitely. I flagged the underlying issue to the dev team as a proper fix for later.

Lesson three: know which layer owns which fix. Downgrading infrastructure to dodge an application-level bug is a trap that's easy to fall into when you can fix it from the Dockerfile but "can" and "should" aren't the same question. Isolate the patch, keep it visible, and hand the real fix to whoever owns that code.

The scan that failed for a reason that had nothing to do with any of this

With the build green, Trivy failed the pipeline:

Total: 4 (HIGH: 4, CRITICAL: 0)
c-ares    CVE-2026-33630
libexpat  CVE-2026-56131 / 56407 / 56408

None of these were application dependencies they were OS packages baked into the nginx:alpine base image, stale relative to Alpine's own security advisories because the base image tag hadn't been rebuilt recently. The fix was a single line at the top of the runner stage:

RUN apk update && apk upgrade --no-cache

Lesson four: a clean base image today doesn't stay clean. Container security scanning isn't just about the app it's about everything shipped inside the image, and base image staleness is one of the most common, least glamorous sources of CVE noise in a pipeline.

Part 2: The Backend Nobody Had Documented

The Django API had never had a real production Dockerfile just a dev one, running manage.py runserver directly against production traffic, with a docker/prod/ directory that looked complete but had never actually been wired up.

Before writing anything, I had to reconstruct the actual setup by hand:

docker exec -it starsight-api-api-1 python --version   # 3.9.25
cat docker/dev/Dockerfile                                # base image, deps
cat docker/dev/entrypoint.sh                              # startup logic
cat app/requirements/*.txt | grep -i gunicorn              # already installed, unused
grep -rn "STATIC_ROOT" app/core/settings*.py               # static file config

This is worth calling out on its own: the existing docker/prod/entrypoint.sh had a bug that would have silently broken production had it ever shipped.

python manage.py migrate --no-input
python manage.py runserver 0.0.0.0:8000
python manage.py loaddata */fixtures/*.json
rm celerybeat.pid
exec "$@"

runserver is a blocking, foreground process it never returns. Every line after it, including exec "$@" (which should hand off to the actual container command, i.e. Gunicorn), would never execute. gunicorn==20.0.4 was sitting in prod.txt, fully installed, completely unused, because the entrypoint script never got past the dev server it was supposed to replace.

There was also a syntax bug in the other environment's entrypoint:

if ["$DATABASE" = "postgres"]

Missing a space after if POSIX shell needs [ "$DATABASE" = "postgres" ], since [ is itself a command. As written, this throws not found and silently skips the entire wait-for-database loop, meaning the app could start racing against a Postgres container that wasn't ready yet, with no visible error.

Neither of these bugs had ever caused a visible incident, because neither entrypoint had ever actually been exercised in a real production deploy. That's the uncomfortable part: untested infrastructure code doesn't fail loudly, it just sits there until the day it does.

Building it properly

The corrected entrypoint dropped the dev-only fixture loading and the blocking runserver call entirely, fixed the shell syntax, and left exactly one job wait for the database, apply already-committed migrations, then hand off to whatever the container's real command is:

#!/bin/sh
set -e

if [ "$DATABASE" = "postgres" ]; then
  while ! nc -z "$SQL_HOST" "$SQL_PORT"; do
    sleep 0.1
  done
fi

python manage.py migrate --no-input
exec "$@"

Notice what's not there: makemigrations. Auto-generating migrations at deploy time is a trap migrations should be written and reviewed in development, committed to the repo, and production should only ever apply what's already there. An entrypoint that can generate schema changes on the fly is an entrypoint that can silently diverge from what a reviewer actually approved.

The Dockerfile itself went through the same evolution as the frontend's first two stages (builder compiles wheels for native extensions like psycopg2 and Pillow, runtime installs only the shared libs those wheels actually need at runtime), then a third base stage once it became clear the ENV/WORKDIR lines were duplicated across both:

FROM python:3.9-slim-bookworm AS base
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1

FROM base AS builder
# compiles wheels, discarded after build

FROM base AS runtime
# copies wheels, runs as non-root, Gunicorn as the actual process

This is worth being precise about: it's not a "GitOps best practice" GitOps is about Git as the source of truth for declarative infrastructure state, completely orthogonal to Dockerfile stage count. It's just good multi-stage design: a shared base stage means PYTHONUNBUFFERED or the workdir path only needs to change in one place, and both builder and runtime inherit it automatically instead of two copies that can silently drift out of sync.

The part that almost got skipped: the reverse proxy nobody remembered

docker/prod/ also contained a full jwilder/nginx-proxy setup its own Dockerfile, an nginx.conf, a vhost.d/default referencing static/media paths under /home/app/web/. None of those paths matched this project's actual STATIC_ROOT convention. That mismatch was the tell: this wasn't a working, tested config, it was a leftover from a boilerplate template, predating the team's move to Nginx Proxy Manager for reverse proxying everything externally. I excluded it entirely rather than trying to make broken paths correct the app just needed to expose a port for NPM to point at, same pattern as every other service on that droplet.

Protecting the thing that actually mattered

The Postgres container behind this API had 46 hours of live data by the time I got to it. The single most important constraint on the entire compose rewrite wasn't performance or elegance, it was: don't touch that volume.

db:
  image: postgres:12.1-alpine
  volumes:
    - postgres_data:/var/lib/postgresql/data

Docker Compose derives a named volume's actual identity from the project directory, not the compose filename so switching from docker-compose.yml to docker-compose.prod.yml in the same directory resolves to the same underlying volume automatically. I verified this explicitly rather than assuming:

docker volume ls | grep postgres_data
# starsight-api_postgres_data

The deploy step in CI also deliberately avoids a full docker compose down:

docker compose -f docker-compose.prod.yml up -d --no-deps api celery celery-beat

--no-deps means only the application containers get recreated on every push. db and redis are never touched by the automated pipeline at all. An automated deploy that can accidentally tear down stateful infrastructure on every merge is a liability waiting for a bad day, better to make that structurally impossible than to rely on remembering not to add a flag.

What Actually Mattered Here

None of these bugs were individually hard. A missing space in a shell conditional. A blocking dev server call. A Node ABI mismatch nobody would notice until runtime. A copy-pasted Dockerfile section from the wrong framework. What made this genuinely tricky was that almost none of it was visible until you went looking the existing docker/prod directory looked complete from a file listing. It had a Dockerfile, an entrypoint, an nginx setup. It just didn't work, and nothing had ever forced it to run.

The actual work of this pipeline rebuild wasn't writing Dockerfiles, it was reconstructing what was true, one cat and docker exec at a time, before writing a single line of infrastructure code. Every fix downstream of that was straightforward. Getting to a Dockerfile you can actually trust starts with refusing to guess at what's already there.

Whether you're debugging, testing a new implementation, or temporarily disabling code, there are times when you need to comment out an entire file in Vim. While many developers rely on plugins, Vim already provides powerful built-in commands that make this incredibly fast.

FOLASAYO SAMUEL OLAYEMI — Sun, 12 Jul 2026 16:25:50 +0000

FOLASAYO SAMUEL OLAYEMI

Jul 12

Comment an Entire File in Vim in Seconds (Two Methods Every Developer Should Know)

#webdev #devops #programming #tutorial

2 min read

Comment an Entire File in Vim in Seconds (Two Methods Every Developer Should Know)

FOLASAYO SAMUEL OLAYEMI — Sun, 12 Jul 2026 16:09:09 +0000

Whether you're debugging, testing a new implementation, or temporarily disabling code, there are times when you need to comment out an entire file in Vim. While many developers rely on plugins, Vim already provides powerful built-in commands that make this incredibly fast.

Here are two efficient approaches.

Method 1: Highlight & Command Mode (Recommended)

This approach is straightforward because you can visually confirm that the entire file is selected before applying the comment.

Step 1: Enter Normal Mode

Press:

Esc

Step 2: Select the Entire File

Type:

ggVG

Here's what each command does:

gg → Jump to the beginning of the file.
V → Enter Visual Line Mode.
G → Extend the selection to the last line.

At this point, the entire file should be highlighted.

Step 3: Add the Comment Prefix

Press:

Vim automatically inserts:

:'<,'>

This means "apply the following command to the selected lines."

Now complete the command:

:'<,'>s/^/# /

Press Enter.

Every line in the file now begins with #.

Use the Appropriate Comment Symbol

Replace # with the correct comment syntax for your language.

Language	Comment Prefix
Python	`#`
Shell	`#`
JavaScript	`//`
TypeScript	`//`
C/C++	`//`
Java	`//`
Go	`//`
Rust	`//`
Lua	`--`
SQL	`--`

For example, to comment every JavaScript line:

:'<,'>s/^/\/\/ /

Method 2: Visual Block Mode

This method leverages Vim's powerful column-editing capability to insert text at the beginning of multiple lines simultaneously.

Step 1: Go to the Beginning

gg

Step 2: Start Visual Block Mode

Press:

Ctrl + V

Step 3: Select Every Line

Press:

Shift + G

The block selection extends to the end of the file.

Step 4: Insert the Comment Character

Press:

Shift + I

This enters Insert Mode at the start of the selected block.

Now type your comment prefix, for example:

//

Step 5: Apply It Everywhere

Press:

Esc
Esc

After the second Esc, Vim inserts the comment prefix on every selected line simultaneously.

It's one of those Vim features that feels like magic the first time you see it.

Uncomment Everything

Need to restore the file?

If every line starts with #, simply run:

:%s/^# //

This searches every line (%) for # at the beginning (^) and removes it.

For JavaScript:

:%s/^\/\/ //

For Lua:

:%s/^-- //

The same principle works for any comment prefix.

Which Method Should You Use?

Both methods are useful, but each has its strengths.

Highlight & Command Mode is easy to understand, visually confirms your selection, and is ideal for search-and-replace operations.
Visual Block Mode is faster once you're comfortable with Vim and is perfect for inserting text at the same column across multiple lines.

If you're just getting started with Vim, I recommend learning Method 1 first. Once you're comfortable with Visual Block Mode, you'll find yourself using it for much more than commenting, it becomes invaluable for editing structured text, logs, configuration files, and source code.

Mastering these native Vim techniques means you can work efficiently without relying on plugins, making your editing experience faster and more portable across environments.

Thanks for reading.
Happy Coding!

Deploying a Containerized Backend to a VPS with Docker Compose + GitHub Actions (A Beginner's Runbook)

FOLASAYO SAMUEL OLAYEMI — Thu, 25 Jun 2026 18:24:48 +0000

This is a complete, copy‑pasteable guide for shipping a backend app to a single Linux server using Docker Compose, with a GitHub Actions pipeline that builds the image, scans it, and deploys it over SSH.

It is written to be language- and framework-agnostic. The examples use a Node/TypeScript API with PostgreSQL, Redis, and a background worker, but the same shape works for Python/Django, Go, Java/Spring, Ruby, etc. Anywhere you see your-app, your-org, your-server-ip, or example.com, substitute your own values.

Every file is included in full, and every non-obvious line is explained. The last section — Common errors and how to fix them — is the part most guides skip, and it is the part that will actually save your afternoon. All of it comes from a real deployment, mistakes included.

1. The mental model (read this first)

Before any YAML, understand the shape of what we're building. There are only three places anything lives:

Your Git repository the single source of truth. Your code, your Dockerfile, your docker-compose.prod.yml, and your CI/CD workflows all live here. You only ever edit things here.
A container registry (we use GHCR, GitHub's built-in registry) — a warehouse for the built application image. CI builds the image and pushes it here.
Your server (a plain Linux VPS) pulls the image from the registry and runs it. It holds exactly two files: the compose file (copied from your repo by the pipeline) and a secrets file (.env) that never leaves the server.

The flow, end to end:

You push to main
      │
      ▼
GitHub Actions: build image ──► push to registry ──► scan image
      │
      ▼
GitHub Actions: SSH to server ──► pull image ──► run migrations ──► start app ──► health-check

The single most important rule: the server is disposable. You never hand-edit files on the server, because the pipeline overwrites them from the repo on every deploy. If you fix something by editing on the server, the next deploy silently erases your fix. Edit in the repo, commit, push. (I learned this one the hard way see the errors section.)

2. Architecture of the running stack

On the server, Docker Compose runs several containers on a private network. Only one port is exposed to the outside world, and even that only on loopback (a reverse proxy / ingress handles TLS in front).

Container	What it is	Exposed?
`postgres`	The database	No — internal only
`pgbouncer`	A connection pooler in front of Postgres	No — internal only
`redis`	Cache / job queue / session store	No — internal only
`migrate`	A one-shot container: runs DB migrations, then exits	No
`api`	Your web API process	`127.0.0.1` only
`worker`	Background job processor (same image as api)	`127.0.0.1` only

Two ideas worth internalizing:

One image, two roles. The api and worker are the same built image. They differ only by the command they run. This keeps builds simple and guarantees the API and worker are always the same version.

Boot order matters. Containers must start in dependency order, or you get race conditions: postgres becomes healthy → pgbouncer and redis become healthy → migrate runs and exits cleanly → only then do api and worker start. Compose enforces this with depends_on + health conditions.

3. The Dockerfile

This is a multi-stage build. Each FROM starts a new stage; only the final stage becomes your shipped image. The point of multi-stage is that build tools (compilers, dev dependencies) stay out of the final image, making it smaller and safer.

# syntax=docker/dockerfile:1

# =========================================================
# Base — package manager + workdir, pinned for reproducibility
# =========================================================
FROM node:22-alpine AS base
RUN apk add --no-cache libc6-compat
RUN npm install -g corepack@latest && corepack enable && corepack prepare pnpm@10.16.1 --activate
WORKDIR /app

# =========================================================
# 1. Dependencies (including dev deps — needed to build)
# =========================================================
FROM base AS deps
COPY package.json pnpm-lock.yaml* ./
RUN pnpm install --frozen-lockfile

# =========================================================
# 2. Build — compile source to /dist
# =========================================================
FROM base AS build
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN pnpm build

# =========================================================
# 3. Production dependencies only (no dev deps)
# =========================================================
FROM base AS prod-deps
COPY package.json pnpm-lock.yaml* ./
RUN pnpm install --prod --frozen-lockfile

# =========================================================
# 4. Runner — the final, minimal image
# =========================================================
FROM node:22-alpine AS runner
# tini = correct PID 1 / signal handling; wget = used by container healthchecks.
RUN apk add --no-cache libc6-compat wget tini

# Remove package managers from the runtime image. Migrations call the migration
# CLI via `node` directly, so npm/pnpm aren't needed at runtime and removing
# them shrinks the attack surface (image scanners flag their bundled CVEs).
RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx \
    /usr/local/bin/corepack /usr/local/lib/node_modules/corepack || true
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=4000
ENV WORKER_PORT=4001

# Run as a NON-root user. Never run app containers as root.
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 appuser

COPY --from=prod-deps --chown=appuser:nodejs /app/node_modules ./node_modules
COPY --from=build     --chown=appuser:nodejs /app/dist         ./dist
COPY --chown=appuser:nodejs package.json ./

USER appuser

EXPOSE 4000 4001

# tini is the entrypoint so signals (Ctrl-C, container stop) are handled properly.
ENTRYPOINT ["/sbin/tini", "--"]
# Default command = API. The worker overrides this in the compose file.
CMD ["node", "dist/main"]

Why each stage exists, in plain terms:

base: shared starting point the language runtime and package manager, pinned to exact versions so builds are reproducible.
deps: installs all dependencies (including dev tools) because you need them to compile.
build: compiles your source into a dist/ folder.
prod-deps: installs only production dependencies into a clean folder — this is what ships.
runner: the final image. It copies in the compiled dist/ and the production-only node_modules, runs as a non-root user, and deliberately removes package managers to reduce CVEs.

Adapting to other stacks: Python would pip install into a venv in a build stage and copy the venv into a slim runtime; Go would compile a static binary in a build stage and copy just the binary into a scratch/distroless image. The pattern is identical: build fat, ship thin, run as non-root.

A small but important detail: the runtime image keeps wget because the container's own healthcheck uses it. If you strip it out, your healthchecks silently break.

4. docker-compose.prod.yml the whole stack in one file

This is the file that runs on the server. It is self-contained: the only other file it needs is .env. No source code on the server, no separate init scripts everything is inlined.

Requires Docker Compose v2.23.1+ (for the inline configs.content feature used below). Check with docker compose version.

name: your-app

# Shared application environment. Secrets are interpolated from .env.
# Defining them once here and reusing via a YAML anchor avoids copy-paste drift.
x-app-env: &app-env
  NODE_ENV: production
  PORT: "4000"
  WORKER_PORT: "4001"
  # The app connects through pgbouncer; the migrator connects to postgres directly.
  DATABASE_URL: postgresql://app_user:${APP_DB_PASSWORD}@pgbouncer:5432/appdb
  DATABASE_MIGRATOR_URL: postgresql://migrator_user:${MIGRATOR_DB_PASSWORD}@postgres:5432/appdb
  REDIS_URL: redis://redis:6379
  JWT_SECRET: ${JWT_SECRET}
  S3_ENDPOINT: ${S3_ENDPOINT}
  S3_BUCKET: ${S3_BUCKET}
  S3_ACCESS_KEY: ${S3_ACCESS_KEY}
  S3_SECRET_KEY: ${S3_SECRET_KEY}
  LOG_LEVEL: ${LOG_LEVEL:-info}

configs:
  # The database init script, inlined. It runs ONCE, only when the postgres
  # data volume is first created (i.e. an empty database). Passwords are
  # interpolated from .env, so the committed compose file contains no secrets.
  postgres_init:
    content: |
      CREATE ROLE app_user      WITH LOGIN PASSWORD '${APP_DB_PASSWORD}';
      CREATE ROLE migrator_user WITH LOGIN PASSWORD '${MIGRATOR_DB_PASSWORD}';

      -- Timeouts set at the ROLE level. Under pgbouncer transaction pooling,
      -- per-session SETs don't reliably stick, so role-level is the safe place.
      ALTER ROLE app_user SET statement_timeout = '15s';
      ALTER ROLE app_user SET idle_in_transaction_session_timeout = '15s';

      GRANT CONNECT ON DATABASE appdb TO app_user, migrator_user;

      -- The migrator needs to create schemas, so it needs CREATE on the database.
      -- Without this, the first migration fails: "permission denied for database".
      GRANT CREATE ON DATABASE appdb TO migrator_user;

      -- Many ORMs write a "migrations" bookkeeping table into a custom schema
      -- BEFORE running the migration that would create that schema a chicken
      -- and egg. Pre-create the schema here so the first run can't fail with
      -- "schema ... does not exist". (Use the schema name YOUR app expects.)
      CREATE SCHEMA IF NOT EXISTS platform AUTHORIZATION migrator_user;

      GRANT USAGE, CREATE ON SCHEMA public TO migrator_user;
      GRANT USAGE          ON SCHEMA public TO app_user;

      -- Tables the migrator creates later should be usable by the app user.
      ALTER DEFAULT PRIVILEGES FOR ROLE migrator_user IN SCHEMA public
        GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
      ALTER DEFAULT PRIVILEGES FOR ROLE migrator_user IN SCHEMA public
        GRANT USAGE, SELECT ON SEQUENCES TO app_user;

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: appdb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    configs:
      - source: postgres_init
        target: /docker-entrypoint-initdb.d/01-init.sql
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres -d appdb']
      interval: 5s
      timeout: 5s
      retries: 10
    networks: [backend]
    # NOT published — the database must never be reachable from the internet.

  pgbouncer:
    image: edoburu/pgbouncer:latest
    restart: unless-stopped
    environment:
      DB_HOST: postgres
      DB_NAME: appdb
      DB_USER: app_user
      DB_PASSWORD: ${APP_DB_PASSWORD:?set APP_DB_PASSWORD in .env}
      AUTH_TYPE: scram-sha-256
      POOL_MODE: transaction
      MAX_CLIENT_CONN: 200
      DEFAULT_POOL_SIZE: 20
      # DB drivers send these as connection "startup parameters". In transaction
      # pooling mode pgbouncer rejects unknown ones with "unsupported startup
      # parameter". List the ones your driver sends so pgbouncer tolerates them.
      IGNORE_STARTUP_PARAMETERS: extra_float_digits,statement_timeout,lock_timeout,idle_in_transaction_session_timeout
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ['CMD', 'pg_isready', '-h', '127.0.0.1', '-p', '5432', '-U', 'app_user', '-d', 'appdb']
      interval: 5s
      timeout: 3s
      retries: 10
    networks: [backend]

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    # noeviction: this Redis holds real state (jobs, sessions), not just cache,
    # so fail loudly rather than silently dropping keys. AOF persists to disk.
    command: ['redis-server', '--maxmemory', '256mb', '--maxmemory-policy', 'noeviction', '--appendonly', 'yes']
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 10
    networks: [backend]

  # One-shot migrations. Must exit 0 before api/worker start.
  migrate:
    image: ${BACKEND_IMAGE:-ghcr.io/your-org/your-app:latest}
    init: true
    restart: 'no'
    command: ['node', 'dist/migrate']   # however YOUR app runs migrations
    environment:
      <<: *app-env
    depends_on:
      postgres:
        condition: service_healthy
    networks: [backend]

  api:
    image: ${BACKEND_IMAGE:-ghcr.io/your-org/your-app:latest}
    init: true
    restart: unless-stopped
    command: ['node', 'dist/main']
    environment:
      <<: *app-env
      PROCESS_ROLE: api
    ports:
      - '127.0.0.1:4000:4000'   # loopback only; reverse proxy sits in front
    depends_on:
      migrate:
        condition: service_completed_successfully
      pgbouncer:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ['CMD', 'wget', '-qO-', 'http://localhost:4000/api/health']
      interval: 15s
      timeout: 5s
      retries: 10
      start_period: 120s   # grace period for cold start before failures count
    networks: [backend]

  worker:
    image: ${BACKEND_IMAGE:-ghcr.io/your-org/your-app:latest}
    init: true
    restart: unless-stopped
    command: ['node', 'dist/worker']
    environment:
      <<: *app-env
      PROCESS_ROLE: worker
    ports:
      - '127.0.0.1:4001:4001'
    depends_on:
      migrate:
        condition: service_completed_successfully
      pgbouncer:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ['CMD', 'wget', '-qO-', 'http://localhost:4001/health']
      interval: 15s
      timeout: 5s
      retries: 10
      start_period: 120s
    networks: [backend]

volumes:
  postgres_data:
  redis_data:

networks:
  backend:
    driver: bridge

The parts that trip people up, explained

name: your-app this is the Compose project name. It is not cosmetic: Compose prefixes your volume names with it (e.g. your-app_postgres_data). If you change this name, Compose looks for differently-named volumes and your database appears to vanish it's still on disk under the old name, but the stack now points at a new, empty volume. Pin this and never change it. This is the single most dangerous footgun in the whole file.

x-app-env: &app-env the &app-env defines a YAML anchor (a reusable block). Each service then writes <<: *app-env to merge that block in (*app-env is a reference to the anchor). This is why all three app containers share identical env without copy-paste. If you delete the anchor line but leave the *app-env references, the file won't parse the references point at nothing.

${VAR:?error message} fail fast. If VAR isn't set in .env, Compose refuses to start with your message instead of booting with a broken config.

${VAR:-default} use default if VAR isn't set. Good for optional tuning values.

configs: with inline content: lets you ship the database init SQL inside the compose file, with no separate file to copy. It's mounted into Postgres's docker-entrypoint-initdb.d/, which Postgres runs only on first boot of an empty data volume. Remember that last part see the migration error below.

depends_on with condition: this is what gives you correct boot order. service_healthy waits for a container's healthcheck to pass; service_completed_successfully waits for the one-shot migrate to exit 0.

start_period: 120s on healthchecks during this window, failing health probes don't count against the container. Apps that map hundreds of routes or warm caches can take a while; without a grace period the orchestrator declares them dead before they finish booting.

Why pgbouncer at all? A connection pooler sits between your app and Postgres so that many short app connections share a small number of real database connections. It dramatically reduces DB load. The catch is transaction pooling mode is stricter about connection "startup parameters" hence IGNORE_STARTUP_PARAMETERS (more in the errors section).

5. The secrets file: .env.example

Commit .env.example (a template with empty values). The real .env is created on the server by hand, once, and is never committed.

# Copy to ".env" (literal name) next to docker-compose.prod.yml ON THE SERVER.
# docker compose reads it automatically for ${...} interpolation.
# NEVER commit the real .env.

# --- Secrets (generate once; store in a password manager) ------------------
# IMPORTANT: these values go INTO connection URLs, so use URL-SAFE values.
# `openssl rand -base64` can emit + / = which break URL parsing — prefer hex:
#   openssl rand -hex 32
POSTGRES_PASSWORD=
APP_DB_PASSWORD=
MIGRATOR_DB_PASSWORD=
JWT_SECRET=                 # at least 32 characters

# --- External object storage (S3-compatible) -------------------------------
S3_ENDPOINT=
S3_BUCKET=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_REGION=

# --- Optional overrides (sensible defaults applied in compose) -------------
# LOG_LEVEL=info

# --- Image (the deploy workflow sets this automatically; only set to pin) --
# BACKEND_IMAGE=ghcr.io/your-org/your-app:latest

Generate passwords with openssl rand -hex 32, not -base64. Base64 output can contain +, /, and =, which break when embedded in a postgresql://user:password@host/db URL. Hex is always URL-safe. This is a genuinely sneaky bug the password "looks fine" but the connection string is silently malformed.

6. CI part 1: code-quality.yml (runs first, on every push)

This workflow runs static analysis / a quality gate. The deploy workflow only triggers if this one succeeds, so it acts as a gate. (Swap SonarQube for whatever you use — ESLint, CodeQL, etc.)

name: CodeQuality Checks

on:
  push:
    branches:
      - main

jobs:
  code-quality:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0   # full history; some scanners need it for blame/new-code

      - name: Static analysis scan
        uses: sonarsource/sonarqube-scan-action@v5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

      - name: Quality Gate
        uses: sonarsource/sonarqube-quality-gate-action@v1
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          # For a SELF-HOSTED scanner you MUST pass the host URL here too, or the
          # gate action defaults to the cloud service, can't find your project,
          # and fails with a confusing HTTP 404.
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

The one thing worth highlighting: a self-hosted quality scanner needs its SONAR_HOST_URL on both the scan step and the gate step. Miss it on the gate step and you get a 404 that looks like a credentials problem but isn't.

7. CI part 2: main.yml (build, scan, deploy)

This is the workhorse. It triggers after the quality workflow completes, and runs four jobs in sequence: dependency audit → build & push image → scan image → deploy.

name: Deploy

on:
  workflow_run:
    workflows: ["CodeQuality Checks"]   # only runs after the quality workflow
    types: [completed]
    branches: [main]

env:
  REGISTRY: ghcr.io

concurrency:
  group: deploy
  cancel-in-progress: false   # never interrupt an in-flight deploy

jobs:
  # 1) Block the deploy if a production dependency has a known high-severity CVE
  dependency-check:
    name: Dependency Vulnerability Check
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - name: Audit production dependencies (blocking)
        run: pnpm audit --prod --audit-level=high
      - name: Audit everything (report only)
        run: pnpm audit --audit-level=high
        continue-on-error: true

  # 2) Build the image once, push to the registry
  build-and-push:
    name: Build & Push Image
    needs: dependency-check
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write   # needed to push to GHCR
    outputs:
      image: ${{ steps.image-name.outputs.image }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - name: Compute lowercase image name
        id: image-name
        run: echo "image=ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT
      - uses: docker/setup-buildx-action@v4
      - name: Log in to registry
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Image metadata (tags)
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ steps.image-name.outputs.image }}
          tags: |
            type=sha,prefix=sha-
            type=raw,value=latest,enable={{is_default_branch}}
      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
          target: runner
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  # 3) Scan the built image for OS/package CVEs; fail on CRITICAL/HIGH
  image-scan:
    name: Container Security Scan
    needs: build-and-push
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
    steps:
      - name: Log in to registry
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Trivy scan
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # pin actions by SHA
        with:
          image-ref: ${{ needs.build-and-push.outputs.image }}:latest
          severity: CRITICAL,HIGH
          exit-code: '1'
          ignore-unfixed: true   # don't fail on CVEs with no fix available yet

  # 4) Deploy: copy compose to server, pull image, migrate, start, health-check
  deploy:
    name: Deploy to Server
    needs: [build-and-push, image-scan]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}

      - name: Ensure deploy directory exists
        uses: appleboy/ssh-action@v1.2.5
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          script: mkdir -p "${{ secrets.DEPLOY_PATH }}"

      # The compose file is the source of truth in git and is shipped to the
      # server EVERY deploy (overwrite: true), so the server can never drift.
      - name: Copy compose file to server
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          source: docker-compose.prod.yml
          target: ${{ secrets.DEPLOY_PATH }}
          overwrite: true

      - name: Deploy over SSH
        uses: appleboy/ssh-action@v1.2.5
        env:
          GHCR_TOKEN: ${{ secrets.GHCR_TOKEN }}
          IMAGE: ${{ needs.build-and-push.outputs.image }}
          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          envs: GHCR_TOKEN,IMAGE,DEPLOY_PATH
          script: |
            set -euo pipefail
            echo "$GHCR_TOKEN" | docker login ghcr.io -u ${{ secrets.GHCR_USERNAME }} --password-stdin

            cd "$DEPLOY_PATH"

            # .env holds all secrets and is never in git — it must already exist.
            if [ ! -f .env ]; then
              echo "ERROR: $DEPLOY_PATH/.env is missing. Create it from .env.example first."
              exit 1
            fi

            export BACKEND_IMAGE="${IMAGE}:latest"
            docker pull "$BACKEND_IMAGE"

            # No `down` named volumes are never touched, so zero data loss and
            # no DB downtime. The one-shot migrate runs forward-only migrations
            # and must exit 0; if it fails, `up` returns non-zero and we stop.
            docker compose -f docker-compose.prod.yml up -d --remove-orphans

            # Wait on the CONTAINER healthcheck (the single source of truth),
            # not a separate host-side probe. 5-minute budget for cold starts.
            echo "Waiting for services to become healthy (up to 5 min)..."
            deadline=$((SECONDS + 300))
            for svc in api worker; do
              cid="$(docker compose -f docker-compose.prod.yml ps -q "$svc")"
              if [ -z "$cid" ]; then
                echo "ERROR: $svc container not created."; docker compose ps; exit 1
              fi
              while true; do
                status="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$cid" 2>/dev/null || echo missing)"
                case "$status" in
                  healthy)   echo "$svc: healthy"; break ;;
                  unhealthy) echo "ERROR: $svc unhealthy. Logs:"; docker compose -f docker-compose.prod.yml logs --tail=100 "$svc"; exit 1 ;;
                esac
                if [ "$SECONDS" -ge "$deadline" ]; then
                  echo "ERROR: $svc not healthy in time. Logs:"; docker compose -f docker-compose.prod.yml logs --tail=100 "$svc"; exit 1
                fi
                sleep 5
              done
            done
            echo "All services healthy."

            # Prune only AFTER success, so the previous image stays for rollback.
            docker image prune -f
            docker compose -f docker-compose.prod.yml ps

Why the deploy job is shaped this way

It triggers off the quality workflow (workflow_run), so a bad commit that fails quality never reaches the server.
The image is built once in CI and pushed to the registry. The server only pulls it never builds. Builds are slow and resource-hungry; your small VPS shouldn't do them.
Actions are pinned third-party actions like Trivy are pinned to a commit SHA, not a moving tag, so a compromised release can't silently change what runs in your pipeline.
No docker compose down bringing the stack down can remove containers and (with -v) volumes. We only ever up -d, which recreates changed containers and leaves the database volume untouched. Zero data-layer downtime.
The health gate waits on the container's own healthcheck via docker inspect, with a 5-minute budget. This is more reliable than a separate curl from the host, because it uses the exact probe defined in compose and accounts for slow cold starts.
Prune happens last only after the new version is confirmed healthy, so the previous image is still around for a fast manual rollback if needed.

8. Keeping dependencies fresh: dependabot.yml

Drop this in .github/dependabot.yml. It opens grouped, scheduled PRs to bump dependencies, GitHub Actions versions, and your Docker base image.

version: 2
updates:
  - package-ecosystem: "npm"     # covers package-lock / pnpm-lock
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 10
    groups:                       # group related bumps into ONE PR to review
      framework:
        patterns: ["@nestjs/*"]
      dev-tooling:
        dependency-type: "development"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      actions:
        patterns: ["*"]

  - package-ecosystem: "docker"   # bumps your Dockerfile base image
    directory: "/"
    schedule:
      interval: "weekly"

Grouping is the feature that makes Dependabot bearable: instead of twenty separate PRs, you get a handful of grouped ones you can review and merge together.

9. Step-by-step: your first deploy

One-time setup

On GitHub — add these repository secrets (Settings → Secrets and variables → Actions):

Secret	What it is
`SERVER_IP`	Your server's IP, e.g. `your-server-ip`
`SERVER_USER`	SSH user, e.g. `deploy` or `root`
`SERVER_SSH_KEY`	The private SSH key for that user (full text)
`DEPLOY_PATH`	Where the app lives on the server, e.g. `/home/apps/your-app`
`GHCR_TOKEN`	A token that can read your registry images (used by the server to pull)
`GHCR_USERNAME`	The username/org for the registry login
`SONAR_TOKEN` / `SONAR_HOST_URL`	If you use a quality gate

On the server — install Docker + Compose, create the deploy directory and the secrets file:

# Install Docker (official convenience script) and verify Compose v2.23.1+
curl -fsSL https://get.docker.com | sh
docker compose version

mkdir -p /home/apps/your-app
cd /home/apps/your-app

# Create the real .env from your template, then fill in generated secrets.
nano .env
# POSTGRES_PASSWORD=...     (openssl rand -hex 32)
# APP_DB_PASSWORD=...       (openssl rand -hex 32)
# MIGRATOR_DB_PASSWORD=...  (openssl rand -hex 32)
# JWT_SECRET=...            (openssl rand -hex 32)
# S3_* = ...

That's it for the server. You will not edit anything else here.

Every deploy after that

# 1. Make your change IN THE REPO (code, or the compose file, or a workflow).
# 2. ALWAYS validate the compose file before committing:
docker compose -f docker-compose.prod.yml config >/dev/null && echo "compose OK"

# 3. Commit and push to main:
git add .
git commit -m "your change"
git push origin main

Then watch the Actions tab. The quality workflow runs, then the deploy workflow builds, scans, and ships. Done.

Make docker compose config a reflex. It parses and fully resolves the file (including anchors and .env interpolation) in about a second. It catches the entire class of "the deploy died instantly on a YAML typo" problems before you push. The vast majority of failed first deploys are a malformed compose file that this one command would have caught.

10. Common errors and how to fix them

This is the section I wish every tutorial had. Every one of these is real. They're roughly in the order you hit them as the pipeline gets further each time.

"My edits to the server file keep reverting!"

Cause: you edited docker-compose.prod.yml on the server, but the pipeline copies the repo's version over it (overwrite: true) on every deploy.
Fix: edit the file in the repo, not the server. The server copy is generated output. This is by design — it guarantees the server matches what's reviewed in git. Retrain the muscle memory: never edit on the box.

SSH step fails with "handshake failed" / "permission denied (publickey)"

Cause: the SERVER_SSH_KEY secret is wrong, or the matching public key isn't in the server's ~/.ssh/authorized_keys.
Fix: put the private key (the whole thing, including the BEGIN/END lines) in the secret. Add its public half to authorized_keys for SERVER_USER. Test locally first: ssh -i your_key user@your-server-ip.

Registry login fails: "Error: Cannot perform an interactive login from a non TTY device" or empty password

Cause: the registry token secret is empty or unset, so the docker login gets no password and tries to go interactive.
Fix: set GHCR_TOKEN (and GHCR_USERNAME). Always pipe it: echo "$GHCR_TOKEN" | docker login ghcr.io -u "$USER" --password-stdin.

"stat /path/.env.docker: no such file or directory"

Cause: the compose file references an env file (env_file: .env.docker) that doesn't exist on the server.
Fix: either create that file, or — better — drop the separate env file and define config inline in the compose x-app-env block, reading secrets from the standard .env. One fewer file to manage.

`yaml: line 2: mapping values are not allowed in this context`

Cause: the compose file is malformed — almost always near the top. The classic version: the x-app-env: &app-env anchor line got deleted (often during hand-edits or a bad copy-paste), leaving the env keys with no parent, or a comment lost its leading #.
Fix: restore the structure. Confirm the anchor exists and the references match. Then docker compose config to verify it parses before committing. If you copied the file from somewhere and it got mangled, download the raw file instead of pasting, pasted text can drop indentation or lines.

Migration fails: `schema "..." does not exist` (Postgres code 3F000)

Cause: the ORM tries to create its migrations bookkeeping table inside a custom schema before the migration that would create that schema has run — a chicken-and-egg on a fresh database.
Fix: pre-create the schema in your DB init SQL: CREATE SCHEMA IF NOT EXISTS your_schema AUTHORIZATION migrator_user;. Important: init SQL only runs on a fresh, empty volume. If your volume already exists, also create the schema manually once:

docker compose exec postgres psql -U postgres -d appdb -c \
  "CREATE SCHEMA IF NOT EXISTS your_schema AUTHORIZATION migrator_user;"

Migration fails: `permission denied for database`

Cause: the migrator role can create schemas/tables but wasn't granted CREATE on the database itself.
Fix: in init SQL: GRANT CREATE ON DATABASE appdb TO migrator_user; (and re-run the manual grant if the volume already exists).

App can't connect: `unsupported startup parameter: statement_timeout` (then `lock_timeout`, etc.)

Cause: your DB driver sets session parameters as connection "startup parameters". PgBouncer in transaction pooling mode rejects any it isn't told to allow — and it surfaces them one at a time, so you fix one and hit the next.
Fix: allow the whole set at once on the pgbouncer service:

IGNORE_STARTUP_PARAMETERS: extra_float_digits,statement_timeout,lock_timeout,idle_in_transaction_session_timeout

Enforce the actual timeouts at the role level in init SQL (ALTER ROLE ... SET statement_timeout = ...), because under transaction pooling per-session SETs don't reliably stick.

Deploy reports "did not become healthy in time" but the app log says it started

Cause: the health gate is stricter or faster than the app's real startup, or the health-check path/port is wrong.
Fix: first confirm the app actually serves the health route from inside the container:

docker compose exec api wget -qO- http://localhost:4000/api/health

If that returns OK, it's a timing issue — raise start_period and the deploy's wait budget. If it 404s, fix the path in the healthcheck test:. If it says wget: not found, your runtime image lacks wget — install it or use a node/curl-based check.

The database "disappeared" after I renamed something

Cause: you changed the compose name: (project name). Volumes are namespaced by project name, so the stack now points at a new, empty volume. Your old data is still on disk under the old name.
Fix: never change the project name. To find orphaned data: docker volume ls | grep postgres. This is why a pg_dump backup before any risky change is non-negotiable in production.

Quality gate fails with HTTP 404 (self-hosted scanner)

Cause: the gate step didn't get the scanner host URL, so it defaulted to the cloud service and couldn't find your project.
Fix: pass SONAR_HOST_URL on both the scan and the gate steps.

Dependabot: "security update not possible"

Cause: a vulnerable transitive dependency has no version that satisfies everything else's constraints yet. Common for deep dev-only dependencies.
Fix: if it's dev-only and below your production audit threshold, it's safe to leave until the ecosystem catches up, or add a temporary override/resolution. Don't let a dev-only advisory block production.

A service crashes with an application error (e.g. `TypeError: ... is not iterable`)

Cause: this is not an infrastructure problem the image built and deployed fine; the app code itself is throwing on boot.
Fix: read it as a signal your pipeline is working it caught a real code bug before declaring success. This belongs to whoever owns that part of the application code, not to the deploy config. No amount of compose/workflow tweaking fixes a code bug. Hand it to the right developer with the exact stack trace.

11. A pre-deploy checklist

Pin this somewhere:

[ ] docker compose -f docker-compose.prod.yml config passes locally
[ ] All changes are in the repo, nothing edited directly on the server
[ ] .env exists on the server with every required key filled in (URL-safe secrets via openssl rand -hex 32)
[ ] The compose project name: is unchanged
[ ] All required GitHub secrets are set
[ ] Third-party actions are pinned to SHAs
[ ] Healthcheck path/port match what your app actually serves
[ ] You have a recent database backup (pg_dump) before any risky change

12. Closing lessons

A few things that, in hindsight, mattered more than any single config line:

One source of truth. Edit in the repo; let the server be disposable. Half-adopting this (editing in both places) is worse than not adopting it at all.
Validate before you push. docker compose config turns a 3-minute failed pipeline into a 1-second local check.
Errors get deeper, which is progress. A YAML parse error → a migration error → a connection error → an app boot error is not "still broken" it's each layer passing in turn. Read the new error as a checkpoint reached.
Know the boundary between infra and app. Connection params, schemas, health timing: infra. A TypeError in your own code: not infra. Recognizing which is which saves you from "fixing" the wrong file.
Protect your data. Pin the project name, never down -v casually, and back up before risky changes. Containers are disposable; your database is not.

Happy shipping.

Setting up a realistic, multi-machine environment on your own laptop used to mean juggling VirtualBox windows, clicking through installers, and hoping you could reproduce the same setup tomorrow. Vagrant replaces all of that with a single text file.

FOLASAYO SAMUEL OLAYEMI — Wed, 24 Jun 2026 07:49:47 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 24

Building a Multi-VM Lab with Vagrant: Two Web Servers and a Database

#webdev #devops #tutorial #automation

6 min read

Building a Multi-VM Lab with Vagrant: Two Web Servers and a Database

FOLASAYO SAMUEL OLAYEMI — Wed, 24 Jun 2026 07:48:37 +0000

Setting up a realistic, multi-machine environment on your own laptop used to mean juggling VirtualBox windows, clicking through installers, and hoping you could reproduce the same setup tomorrow. Vagrant replaces all of that with a single text file.

In this article we'll build a three-machine lab, two Ubuntu web servers and one CentOS database server, wired together on a private network, with the database node automatically provisioned at boot.

By the end you'll understand not just what the configuration says, but why each line is there and what can go wrong.

What We're Building

The target topology is simple but representative of a real application stack:

VM	Operating System	Role	Private IP
web01	Ubuntu 20.04 LTS	Web server	192.168.56.11
web02	Ubuntu 20.04 LTS	Web server	192.168.56.12
db01	CentOS 7	Database server	192.168.56.13

All three machines sit on the same host-only private network (192.168.56.0/24), which lets them talk to each other while staying isolated from the outside world. The database node, db01, gets a provisioning script that sets its hostname, populates /etc/hosts, and installs a running MariaDB instance, so the moment vagrant up finishes, the box is ready to accept connections.

A Quick Word on Vagrant

Vagrant is an infrastructure-as-code tool for managing virtual machines. You describe the machines you want in a file called a Vagrantfile, and Vagrant talks to a provider (VirtualBox by default) to create them. The two ideas that make Vagrant powerful are boxes and provisioners.

A box is a pre-packaged base image, for example ubuntu/focal64 is a minimal Ubuntu 20.04 install. Instead of running an OS installer, Vagrant downloads the box once and clones it for each machine. A provisioner is the code that runs the first time a machine boots (and again on demand), turning a generic base image into the specific server you need. Together they give you environments that are disposable, repeatable, and version-controllable.

The Complete Vagrantfile

Here is the configuration in full. We'll dissect it section by section afterward.

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|

  # ---------------------------------------------------------------
  # web01 - Ubuntu 20.04 (Focal Fossa)
  # ---------------------------------------------------------------
  config.vm.define "web01" do |web01|
    web01.vm.box = "ubuntu/focal64"
    web01.vm.hostname = "web01"
    web01.vm.network "private_network", ip: "192.168.56.11"
  end

  # ---------------------------------------------------------------
  # web02 - Ubuntu 20.04 (Focal Fossa)
  # ---------------------------------------------------------------
  config.vm.define "web02" do |web02|
    web02.vm.box = "ubuntu/focal64"
    web02.vm.hostname = "web02"
    web02.vm.network "private_network", ip: "192.168.56.12"
  end

  # ---------------------------------------------------------------
  # db01 - CentOS 7  (with provisioning + hostname configuration)
  # ---------------------------------------------------------------
  config.vm.define "db01" do |db01|
    db01.vm.box = "centos/7"
    db01.vm.hostname = "db01"
    db01.vm.network "private_network", ip: "192.168.56.13"

    # Provisioning for db01
    db01.vm.provision "shell", inline: <<-SHELL
      echo "==== Provisioning db01 ===="

      # Ensure hostname is configured persistently
      hostnamectl set-hostname db01

      # Add host entries for the other VMs (handy for app -> db lookups)
      cat >> /etc/hosts <<-HOSTS
        192.168.56.11  web01
        192.168.56.12  web02
        192.168.56.13  db01
      HOSTS

      # Update packages and install MariaDB (MySQL) server
      yum update -y
      yum install -y mariadb-server mariadb

      # Enable and start the database service
      systemctl enable mariadb
      systemctl start mariadb

      echo "==== db01 provisioning complete ===="
    SHELL
  end

end

Breaking It Down

The configuration block

Vagrant.configure("2") do |config|
  ...
end

The Vagrantfile is written in Ruby, and everything lives inside a single configuration block. The "2" is the configuration version, version 2 has been the standard for years and covers every modern Vagrant release. The config object passed into the block is the handle through which you describe global settings and individual machines.

Defining multiple machines

The key to a multi-VM setup is config.vm.define. Each call carves out a named machine with its own nested configuration:

config.vm.define "web01" do |web01|
  ...
end

The name you pass ("web01") becomes the identifier you use on the command line, for example vagrant ssh web01 or vagrant provision db01. Inside the block you configure that machine in isolation, which is what lets web01, web02, and db01 run different operating systems and carry different settings within one file.

Choosing a box

web01.vm.box = "ubuntu/focal64"

ubuntu/focal64 is the official Ubuntu 20.04 LTS box (Focal Fossa is the 20.04 codename). The database node instead uses centos/7. Boxes are downloaded from Vagrant Cloud the first time they're needed and then cached locally, so subsequent machines using the same box start almost instantly.

Setting the hostname

web01.vm.hostname = "web01"

This tells Vagrant to set the machine's hostname during boot. It's a convenience that keeps your shell prompts readable and gives each box a stable identity. For db01 we also set the hostname inside the provisioning script with hostnamectl — more on why below.

Private networking

web01.vm.network "private_network", ip: "192.168.56.11"

A private_network creates a host-only network: the VMs can reach each other and the host machine, but they aren't directly exposed to the wider LAN or internet. Assigning static IPs in the same subnet (192.168.56.x) means web01 can always find db01 at 192.168.56.13, which is exactly what an application server needs to locate its database.

The 192.168.56.0/24 range matters. Recent versions of VirtualBox restrict which host-only networks are allowed for security reasons, and 192.168.56.0/21 is the default permitted range. Using an IP outside it will cause Vagrant to fail with a network validation error unless you explicitly whitelist the range in /etc/vbox/networks.conf.

Provisioning the database node

The most interesting part is the shell provisioner attached to db01:

db01.vm.provision "shell", inline: <<-SHELL
  ...
SHELL

The <<-SHELL ... SHELL syntax is a Ruby heredoc, a multi-line string that Vagrant uploads to the guest and runs as root on first boot. Walking through what it does:

Hostname configuration. hostnamectl set-hostname db01 writes the hostname persistently through systemd. Even though Vagrant's hostname setting already does this, calling hostnamectl inside the script makes the intent explicit and guarantees it survives regardless of box quirks, a small belt-and-suspenders habit that's common in real provisioning code.

Host resolution. The script appends entries to /etc/hosts so that names like web01 and web02 resolve to their private IPs from inside db01. In a lab without a DNS server, this is the simplest way to let machines refer to each other by name instead of memorizing addresses.

Package installation. yum update -y refreshes the package metadata, then yum install -y mariadb-server mariadb pulls in the MariaDB database engine (the community fork of MySQL that ships in the CentOS 7 repositories).

Service management. Finally, systemctl enable mariadb makes the database start automatically on every boot, and systemctl start mariadb brings it up immediately so you don't have to reboot to use it.

Running the Lab

With the Vagrantfile saved in an empty directory, the workflow is short:

# Bring up all three machines
vagrant up

# SSH into any machine by name
vagrant ssh db01

# Re-run only db01's provisioning after editing the script
vagrant provision db01

# Check the status of every machine
vagrant status

# Tear everything down when you're done
vagrant destroy -f

The first vagrant up will take a few minutes as boxes download and db01 runs its provisioning. Subsequent boots are much faster because the boxes are already cached.

Common Pitfalls

A few things tend to trip people up the first time they run a setup like this.

The CentOS 7 box is end-of-life. CentOS 7 reached end of life in mid-2024, and its package mirrors have been moving to the CentOS Vault. If yum update fails to reach a mirror, you may need to repoint yum at the vault URLs, or switch to a maintained box such as generic/centos7. For brand-new labs, consider Rocky Linux or AlmaLinux as drop-in CentOS successors.

Host-only network range. As noted earlier, if you pick IPs outside 192.168.56.0/21 you'll hit a VirtualBox validation error. Either stay within the default range or add your range to /etc/vbox/networks.conf.

Heredoc indentation. When you append to /etc/hosts using a nested heredoc, leading whitespace from the indented script lines is carried into the file. It's harmless for /etc/hosts parsing, but if you want perfectly clean entries, use <<-HOSTS with tab indentation (which the dash strips) or drop the indentation entirely.

Provisioning only runs once. By default, provisioners execute only on the first vagrant up or when you explicitly call vagrant provision. Editing the script and re-running vagrant up on an already-running machine won't re-provision it, use vagrant provision db01 or vagrant reload --provision.

Where to Go Next

This lab is a foundation. Natural extensions include adding provisioning to the two web servers so they install and start Nginx or Apache, configuring the web tier to connect to MariaDB on db01, securing the database with mysql_secure_installation, or moving from inline shell scripts to a configuration-management tool like Ansible once your provisioning logic grows beyond a handful of commands. You might also tune the VM resources (CPU and memory) per machine using a config.vm.provider block when the default allocation isn't enough.

The real value of expressing all of this in a Vagrantfile is reproducibility: anyone who clones your repository and runs vagrant up gets the exact same three-machine environment, every time, on any machine that has Vagrant and VirtualBox installed. That predictability is the whole point, and it's why a few dozen lines of Ruby can replace an afternoon of manual setup.

One of the most confusing errors you can face while deploying a Node.js or Docker-based application

FOLASAYO SAMUEL OLAYEMI — Tue, 23 Jun 2026 21:50:34 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 23

Fixing “Git Divergent Branches” on a Production Server (Real DevOps Debugging Walkthrough)

#ai #devops #tutorial #programming

2 min read

Fixing “Git Divergent Branches” on a Production Server (Real DevOps Debugging Walkthrough)

FOLASAYO SAMUEL OLAYEMI — Tue, 23 Jun 2026 21:48:29 +0000

One of the most confusing errors you can face while deploying a Node.js or Docker-based application is:

fatal: Need to specify how to reconcile divergent branches

At first glance, it looks like a Git bug. In reality, it is Git doing exactly what it should do, protecting you from overwriting history.

In this article, I’ll break down a real production incident where a deployment failed due to divergent Git branches, how we diagnosed it, and the correct DevOps fix.

The Problem

A simple deployment script was running:

git pull
docker compose down --remove-orphans
docker compose up --build -d

But it failed with:

fatal: Need to specify how to reconcile divergent branches

This stopped deployment completely.

What Git Was Telling Us

To understand the issue, we ran:

git rev-list --left-right --count HEAD...origin/main

Output:

1       16

This means:

1 commit exists locally on the server
16 commits exist on GitHub

So the branches had diverged.

Why This Happens (Important)

This usually happens when:

Someone runs git commit directly on a server
A previous deployment used git pull with merge commits
History between local and remote is no longer linear

Git refuses to guess whether you want to:

Merge
Rebase
Or reject changes

So it throws an error.

Deep Diagnosis

We inspected the commits:

git log --oneline origin/main..HEAD

Result:

6d9046b Merge pull request #222

Then:

git log --oneline HEAD..origin/main

Showed multiple new GitHub PR merges.

Conclusion:

The server was behind GitHub
The “local commit” was already part of repo history
No real production changes existed on server

The Real Fix (Production Safe)

For deployment servers, you should NEVER rely on git pull.

Instead, use a deterministic reset:

git fetch origin
git reset --hard origin/main

Then redeploy:

docker compose down --remove-orphans
docker compose up --build -d

Why This Works

This approach ensures:

Server always matches GitHub exactly
No merge conflicts in production
No accidental local commits survive
Fully reproducible deployments

This is the standard CI/CD pattern used in production environments.

The Broken Approach

Avoid this on servers:

git pull

Why?

Because it:

May trigger merge conflicts
Depends on local history state
Can break deployments unexpectedly

Best Practice Deployment Script

cd opt/yourprojectdirectory

echo "Fetching latest code..."
git fetch origin

echo "Resetting to latest main..."
git reset --hard origin/main

echo "Rebuilding containers..."
docker compose down --remove-orphans
docker compose up --build -d

echo "Deployment successful"

Key Lesson

Production servers should not “merge code.”
They should mirror GitHub exactly.

Conclusion

This issue looks scary at first, but it’s actually a simple Git history mismatch problem.

Once you understand:

HEAD
origin/main
divergence

…you can fix it in under 30 seconds.

If you're doing DevOps or managing deployments, this is one of those fundamentals that will save you from late-night production panic.

If you enjoyed this breakdown, I’ll share more real-world DevOps debugging stories like this.

It is one of the most frustrating experiences in online learning: you sit down to focus on a Udemy course, but the video player constantly pauses, freezes, or refuses to load. Meanwhile, YouTube, Netflix, and every other app on your Mac run perfectly fine.

FOLASAYO SAMUEL OLAYEMI — Sat, 13 Jun 2026 04:22:16 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 13

How to Fix Udemy Videos Constantly Pausing on macOS (When Other Apps Work Fine)

#macos #chrome #troubleshooting #productivity

4 min read

DEV Community: FOLASAYO SAMUEL OLAYEMI

Quick system design question: Do you actually know the structural difference between a Reverse Proxy, a Load Balancer, and an API Gateway? (Hint: They aren't the same thing!).

Reverse Proxy vs Load Balancer vs API Gateway: The Real Difference

Reverse Proxy vs Load Balancer vs API Gateway: The Real Difference

1. The Starting Point: Direct Connection (Layer 0)

2. The Protective Buffer: Reverse Proxy

Forward Proxy vs. Reverse Proxy

Core Responsibilities of a Reverse Proxy

3. Scaling Horizontally: The Load Balancer

Traffic Distribution Strategies

Layer 4 vs. Layer 7 Load Balancing

High Availability through Health Checks

4. Decoupling Microservices: The API Gateway

Advanced Features of an API Gateway

5. Why the Terms Blur: The Feature Spectrum

6. How They Layer Together in Production

Summary Checklist: Which One Do You Need?

Setting Up a Production CI/CD Pipeline for a Python/Django App

The Shape of the Pipeline

Step 1: The Dockerfile

Step 2: A Real Entrypoint

Step 3: The GitHub Actions Workflow

Step 4: The Production Compose File

Step 5: Verify Before You Trust It

Why This Shape, Specifically

Debugging a Legacy CRA + Django Deployment Pipeline: A DevOps Postmortem

Part 1: The Frontend That Wasn't Next.js

The Node version trap

OpenSSL, then postcss, then Node itself

The scan that failed for a reason that had nothing to do with any of this

Part 2: The Backend Nobody Had Documented

Building it properly

The part that almost got skipped: the reverse proxy nobody remembered

Protecting the thing that actually mattered

What Actually Mattered Here

Whether you're debugging, testing a new implementation, or temporarily disabling code, there are times when you need to comment out an entire file in Vim. While many developers rely on plugins, Vim already provides powerful built-in commands that make this incredibly fast.

Comment an Entire File in Vim in Seconds (Two Methods Every Developer Should Know)

Comment an Entire File in Vim in Seconds (Two Methods Every Developer Should Know)

Method 1: Highlight & Command Mode (Recommended)

Step 1: Enter Normal Mode

Step 2: Select the Entire File

Step 3: Add the Comment Prefix

Use the Appropriate Comment Symbol

Method 2: Visual Block Mode

Step 1: Go to the Beginning

Step 2: Start Visual Block Mode

Step 3: Select Every Line

Step 4: Insert the Comment Character

Step 5: Apply It Everywhere

Uncomment Everything

Which Method Should You Use?

Deploying a Containerized Backend to a VPS with Docker Compose + GitHub Actions (A Beginner's Runbook)

1. The mental model (read this first)

2. Architecture of the running stack

3. The Dockerfile

4. docker-compose.prod.yml the whole stack in one file

The parts that trip people up, explained

5. The secrets file: .env.example

6. CI part 1: code-quality.yml (runs first, on every push)

7. CI part 2: main.yml (build, scan, deploy)

Why the deploy job is shaped this way

8. Keeping dependencies fresh: dependabot.yml

9. Step-by-step: your first deploy

One-time setup

Every deploy after that

10. Common errors and how to fix them

"My edits to the server file keep reverting!"

SSH step fails with "handshake failed" / "permission denied (publickey)"

Registry login fails: "Error: Cannot perform an interactive login from a non TTY device" or empty password

"stat /path/.env.docker: no such file or directory"

yaml: line 2: mapping values are not allowed in this context

Migration fails: schema "..." does not exist (Postgres code 3F000)

Migration fails: permission denied for database

App can't connect: unsupported startup parameter: statement_timeout (then lock_timeout, etc.)

Deploy reports "did not become healthy in time" but the app log says it started

The database "disappeared" after I renamed something

Quality gate fails with HTTP 404 (self-hosted scanner)

Dependabot: "security update not possible"

A service crashes with an application error (e.g. TypeError: ... is not iterable)

11. A pre-deploy checklist

`yaml: line 2: mapping values are not allowed in this context`

Migration fails: `schema "..." does not exist` (Postgres code 3F000)

Migration fails: `permission denied for database`

App can't connect: `unsupported startup parameter: statement_timeout` (then `lock_timeout`, etc.)

A service crashes with an application error (e.g. `TypeError: ... is not iterable`)