DEV Community: FOLASAYO SAMUEL OLAYEMI

How to Give a Linux User Scoped Access to a Specific Docker Container

FOLASAYO SAMUEL OLAYEMI — Wed, 29 Jul 2026 14:27:10 +0000

FOLASAYO SAMUEL OLAYEMI

Jul 29

How to Give a Linux User Scoped Access to a Specific Docker Container (Without Exposing the Entire Server)

#productivity #devops #linux #tutorial

7 min read

How to Give a Linux User Scoped Access to a Specific Docker Container (Without Exposing the Entire Server)

FOLASAYO SAMUEL OLAYEMI — Wed, 29 Jul 2026 14:26:48 +0000

When you run multiple services on a shared Linux server, one of the most common DevOps challenges is giving a teammate or a client access to exactly one running service: nothing more, nothing less. You don't want to hand them root access, you don't want them browsing other application directories, and you don't want them accidentally taking down unrelated containers.

This article walks through a practical, real-world approach to scoped Docker container access on a shared Linux server. By the end, you will have a second Linux user who logs in and lands directly inside a specific Docker container, with visibility into the app's configuration files and real-time logs: and no access to anything else on the server.

The Setup

We have a Linux server running several Docker Compose stacks. One of those stacks is a payment service. A developer needs access to that payment service: they need to inspect the running container, read the environment configuration, and tail logs in real time. They should not have access to other stacks or host-level system files.

What we will do:

Verify the user exists on the server
Add them to the Docker group
Create a restricted login shell that drops them into the target container
Set the correct directory permissions so they can read the app config files
Verify everything works end to end

Step 1: Check If the User Already Exists

Before creating a new user, check whether one has already been provisioned:

grep -iE 'myapp-dev' /etc/passwd

What this does:

grep searches for a pattern in a file
-i makes the search case-insensitive
-E enables extended regular expressions (useful if you want to match patterns like myapp|otherapp)
/etc/passwd is the file Linux uses to store user account information: every user on the system has a line here

Example output:

myapp-dev:x:1002:1002:,,,:/home/myapp-dev:/bin/bash

Each field separated by : means:

myapp-dev: username
x: password is stored in /etc/shadow (hashed)
1002: user ID (UID)
1002: primary group ID (GID)
,,,: optional comment/GECOS field (name, phone, etc.)
/home/myapp-dev: home directory
/bin/bash: login shell

If the user does not exist, create them:

useradd -m -s /bin/bash myapp-dev
passwd myapp-dev

useradd: creates a new user account
-m: creates a home directory at /home/myapp-dev
-s /bin/bash: sets bash as the default shell
passwd myapp-dev: sets a password for the user interactively

Step 2: Check the User's Current Groups

id myapp-dev

What this does:
id prints the user ID, primary group ID, and all supplementary groups a user belongs to.

Example output:

uid=1002(myapp-dev) gid=1002(myapp-dev) groups=1002(myapp-dev),1003(myapp)

This tells you the user exists but is not yet in the docker group, meaning they cannot interact with Docker at all yet.

Step 3: Add the User to the Docker Group

usermod -aG docker myapp-dev

What this does:

usermod: modifies an existing user account
-a: append (do not replace existing groups)
-G docker: add the user to the docker supplementary group

Why this matters: Docker's socket (/var/run/docker.sock) is only accessible to root and members of the docker group. Without this step, the user cannot run any docker commands at all.

Security note: Adding a user to the docker group effectively gives them root-equivalent access to the host via Docker (e.g. they could mount the host filesystem). For a trusted developer in a dev environment this is acceptable. In production, consider rootless Docker or more granular controls.

Verify the group was added:

id myapp-dev

You should now see docker in their groups:

uid=1002(myapp-dev) gid=1002(myapp-dev) groups=1002(myapp-dev),998(docker),1003(myapp)

Step 4: Create a Restricted Login Shell

Instead of giving the user a full bash session on the host, we create a small shell script that immediately drops them into the target container when they log in.

cat > /usr/local/bin/myapp-shell << 'EOF'
#!/bin/bash
exec docker exec -it my-payment-container /bin/sh
EOF

What this does:

cat >: writes the following content into a file
<< 'EOF' ... EOF: a heredoc block; everything between the two EOF markers is written as-is to the file
#!/bin/bash: shebang line; tells the OS to run this script with bash
exec: replaces the current shell process with the docker exec command (no parent shell remains)
docker exec: runs a command inside an already-running container
-i: keeps STDIN open (interactive mode)
-t: allocates a pseudo-TTY (gives you a proper terminal experience)
my-payment-container: the name of your target container (get this from docker ps)
/bin/sh: the shell to open inside the container (use /bin/bash if the container image has bash installed)

Make the script executable:

chmod +x /usr/local/bin/myapp-shell

chmod: changes file permissions
+x: adds the execute bit, making it runnable as a program

Alternative shells you could use: If the container has bash, replace /bin/sh with /bin/bash for a better experience. Some minimal images (Alpine-based) only have /bin/sh.

Step 5: Set the Restricted Shell as the User's Login Shell

usermod -s /usr/local/bin/myapp-shell myapp-dev

usermod: modifies the user account
-s: sets the login shell
/usr/local/bin/myapp-shell: the script we just created

Now whenever myapp-dev logs in via SSH or su, instead of getting a bash prompt on the host, they are immediately placed inside the container.

Verify the change:

grep myapp-dev /etc/passwd

The last field should now show:

myapp-dev:x:1002:1002:,,,:/home/myapp-dev:/usr/local/bin/myapp-shell

Step 6: Give the User Visibility Into the App Directory

By default the user's home directory is /home/myapp-dev. The actual application files (.env, docker-compose.yml, logs) live in a different directory, for example /home/apps/my-payment-service. We need to:

Give the user's group read access to that directory
Change their home directory so they land there on login

Set group ownership and permissions:

chown root:myapp /home/apps/my-payment-service
chmod 750 /home/apps/my-payment-service
chmod g+r /home/apps/my-payment-service/.env

chown: changes file/directory ownership
root:myapp: sets owner to root, group to myapp (the group myapp-dev already belongs to)
chmod 750: owner gets read/write/execute, group gets read/execute, others get nothing
g+r: adds read permission for the group on the .env file specifically

Change the user's home directory:

If the user has an active session, kill it first:

pkill -u myapp-dev

pkill: sends a signal to processes matching a criterion
-u myapp-dev: matches all processes owned by myapp-dev
This sends SIGTERM by default, gracefully terminating their session

Then update the home directory:

usermod -d /home/apps/my-payment-service myapp-dev

-d: sets the user's home directory

Now when myapp-dev logs in they land directly at /home/apps/my-payment-service and can see docker-compose.yml, .env, and any log directories.

Step 7: Verify End to End

Switch to the user and test:

su - myapp-dev

su: substitute user (switch to another user)
-: loads the full login environment for that user (home directory, shell, environment variables)

If the login shell is set to the container script, you will land directly inside the container:

/ $

If the login shell is set to bash, you will land in the app directory:

myapp-dev@server:/home/apps/my-payment-service$ ls -a
.  ..  .env  docker-compose.yml  live-logs

From there, the user can also interact with Docker normally:

# See running containers in this stack
docker compose -f docker-compose.yml ps

# Tail real-time logs
docker logs -f my-payment-container

# Shell into the container manually
docker exec -it my-payment-container /bin/sh

What Both Users Share

Once this is set up, both root and myapp-dev are operating on the same running containers. This means:

docker compose ps: both see identical container states
docker logs -f my-payment-container: both stream the same real-time log output simultaneously
docker exec -it my-payment-container /bin/sh: both can open shells inside the container at the same time
Any restart or config change made by either user affects the same running service

This is the intended behaviour for a shared dev environment: one running stack, multiple people with visibility into it.

Understanding the Two Access Modes

Depending on how you configure the login shell, you get two different access patterns:

Mode	Login Shell	Where They Land	What They See
Container-only	`/usr/local/bin/myapp-shell`	Inside the container filesystem	Container files only, no host files
Host directory scoped	`/bin/bash`	App directory on the host	`.env`, `docker-compose.yml`, logs, and Docker CLI

For a developer who needs to read config, tail logs, and inspect the compose setup: the host directory scoped mode is more practical. For a user who only needs to run commands inside the application process: the container-only mode is more restrictive and appropriate.

Quick Reference: All Commands

# Check if user exists
grep -iE 'myapp-dev' /etc/passwd

# Create user if needed
useradd -m -s /bin/bash myapp-dev
passwd myapp-dev

# Check current groups
id myapp-dev

# Add to docker group
usermod -aG docker myapp-dev

# Create restricted container shell
cat > /usr/local/bin/myapp-shell << 'EOF'
#!/bin/bash
exec docker exec -it my-payment-container /bin/sh
EOF
chmod +x /usr/local/bin/myapp-shell

# Set as login shell
usermod -s /usr/local/bin/myapp-shell myapp-dev

# Or set bash as login shell (host access mode)
usermod -s /bin/bash myapp-dev

# Set app directory permissions
chown root:myapp /home/apps/my-payment-service
chmod 750 /home/apps/my-payment-service

# Kill active session before modifying home dir
pkill -u myapp-dev

# Change home directory
usermod -d /home/apps/my-payment-service myapp-dev

# Test login
su - myapp-dev

Conclusion

With a few targeted usermod commands, a wrapper shell script, and careful directory permissions, you can give a developer or client scoped access to a specific Docker service running on a shared server: without handing them the keys to everything else.

This pattern is particularly useful in multi-tenant dev environments where multiple application stacks share a single droplet or VM and you need to delegate access per service without spinning up separate servers or managing complex ACLs.

For production environments, consider extending this pattern with:

Rootless Docker: each user runs their own Docker daemon with no shared socket
Sudoers rules: restrict which Docker commands a user can run via sudo
Audit logging: use auditd to log all Docker exec sessions for the scoped user

Thanks for reading...

Branch-Based CI/CD: Quality Gate to Multi-Environment Deploy with GitHub Actions

FOLASAYO SAMUEL OLAYEMI — Mon, 27 Jul 2026 11:06:16 +0000

A complete, reusable pattern for wiring a code-quality gate (SonarQube) to Docker
build, image scanning, and SSH-based deployment across development, staging, and
production using a single reusable workflow and GitHub Environments for secrets
and approval gates.

This document explains not just what to copy, but why each piece is shaped the
way it is, including the failure modes that quietly break this kind of pipeline.

1. The problem this solves

A common goal: when code lands on a branch and passes the quality gate, automatically
build a Docker image, scan it for vulnerabilities, and deploy it to the server that
matches that branch develop to dev, staging to staging, main to production, with production requiring a human to approve the release.

The naive approach is one deploy file per environment, each triggered independently.
That works but rots fast: three files drift apart, a fix in one is forgotten in the
others, and secrets get duplicated. The pattern below uses one reusable deploy
workflow parameterized by environment, called from the quality-gate workflow, with
per-environment secrets and protection rules living in GitHub Environments.

2. The `workflow_run` trap (why the obvious approach fails silently)

The instinctive way to chain "run B after A finishes" is the workflow_run trigger:

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

This looks correct and frequently does nothing at all. Two rules cause most of the
silent failures:

Rule 1: workflow_run is armed only from the default branch. GitHub reads a
workflow_run trigger definition only from the copy of the file on the repository's
default branch. If your default branch is, say, main (or something unexpected like a
codex/* branch) and the deploy file exists only on develop, the trigger is never
registered. The upstream workflow can pass a thousand times; nothing listens. The
branches: filter does not change this — the file must physically exist on the default
branch to be active, even though the filter then restricts it to acting on develop.

A quick way to discover your real default branch is the "This branch is N commits ahead
of X" banner on the repo's Code tab — X is the default branch GitHub compares against.

Rule 2: the branches: filter matches the upstream run's head branch. It does
not mean "the target branch." If the upstream (quality) workflow runs on
pull_request, its head branch is the PR's source branch (e.g. feature/x), not
develop, so branches: [develop] never matches. It only lines up when the upstream
runs on push to develop.

Because of these two traps and because relying on the default branch is undesirable
when your default branch is not the branch you deploy from — this document avoids
workflow_run entirely and uses a reusable workflow instead.

3. Why a reusable workflow (`workflow_call`) is the right primitive

A workflow invoked with workflow_call is resolved from the caller's ref, not the
default branch. If the quality workflow runs on develop and calls the deploy workflow
with uses: ./.github/workflows/deploy.yml, GitHub loads the deploy file from
develop. No default-branch dependency, no head-branch filter guessing. The two
workflows also appear as a single run graph with a real dependency edge, so a failed
build visibly blocks the deploy.

workflow_dispatch (manual/API trigger) is not an escape hatch here: dispatching via
the API has the same default-branch requirement as workflow_run. Reusable
workflow_call is the only model fully independent of the default branch.

4. Architecture overview

push to develop / staging / main
        │
        ▼
┌─────────────────────────┐
│  Quality workflow        │   runs on: push [develop, staging, main]
│  (SonarQube scan + gate) │
└───────────┬─────────────┘
            │ success()
            ▼
┌─────────────────────────┐
│  resolve-env job         │   maps branch → environment / tag / path
└───────────┬─────────────┘
            │ outputs
            ▼
┌─────────────────────────────────────────────┐
│  deploy.yml (reusable, workflow_call)         │
│                                               │
│  dependency-check → build-and-push →          │
│  image-scan → deploy (Environment-gated)      │
└───────────────────────────────────────────────┘
            │
            ▼
   dev / staging / production server (SSH + docker compose)

Branch-to-environment mapping:

Branch	Environment	Image tag	Deploy path	Approval
`develop`	`dev`	`dev`	`/home/apps/pmis-web-dev`	none
`staging`	`staging`	`staging`	`/home/apps/pmis-web-staging`	none
`main`	`production`	`prod`	`/home/apps/pmis-web-prod`	required

5. Prerequisites: GitHub Environments

Before the workflows will work, create three Environments under
Settings → Environments: dev, staging, and production.

Environments do two jobs here. First, they scope secrets: each environment holds its
own copy of the deploy secrets pointing at that environment's server. Second, they
enforce protection rules: adding required reviewers to production makes the deploy
job pause and wait for a human to approve before it runs.

Inside each environment, define these secrets (same key names, different values per
environment):

Secret	Meaning
`SERVER_IP`	Target host for that environment
`SERVER_USER`	SSH user
`SERVER_SSH_KEY`	Private key for that user
`GHCR_TOKEN`	Token with `read:packages` for pulling on server
`GHCR_USERNAME`	GHCR username matching the token
`NEXT_PUBLIC_API_URL`	Public API URL baked into the build for that env

Repository-level (or organization-level) secrets, shared across environments:

Secret	Meaning
`SONAR_TOKEN`	SonarQube auth token
`SONAR_HOST_URL`	SonarQube server URL

GITHUB_TOKEN is provided automatically; no need to create it.

Note: the key names here are env-neutral (SERVER_IP rather than DEV_SERVER_IP).
Because each environment supplies its own value, there is no reason to prefix them
with DEV_. Pick one convention and use it consistently in both the workflow files
and every environment.

6. The quality-gate workflow (the caller)

This runs on every push to the three deployable branches, runs the SonarQube scan and
quality gate, then only if the gate passed and the push was to a known branch, resolves the target environment and calls the reusable deploy workflow.

name: CodeQuality Checks

on:
  push:
    branches:
      - develop
      - staging
      - main

jobs:
  # ─────────────────────────────────────────────────────
  # 1. SonarQube scan + quality gate
  # ─────────────────────────────────────────────────────
  code-quality:
    name: Code Quality
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0            # full history so Sonar can attribute blame

      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

      - name: SonarQube Quality Gate
        uses: sonarsource/sonarqube-quality-gate-action@master
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

  # ─────────────────────────────────────────────────────
  # 2. Map the pushed branch to an environment
  # ─────────────────────────────────────────────────────
  resolve-env:
    name: Resolve Target Environment
    needs: [code-quality]
    if: >-
      ${{ success() &&
          contains(fromJSON('["refs/heads/develop","refs/heads/staging","refs/heads/main"]'),
                   github.ref) }}
    runs-on: ubuntu-latest
    outputs:
      environment: ${{ steps.map.outputs.environment }}
      image_tag:   ${{ steps.map.outputs.image_tag }}
      deploy_path: ${{ steps.map.outputs.deploy_path }}
    steps:
      - name: Map branch to environment
        id: map
        run: |
          case "${{ github.ref }}" in
            refs/heads/develop)
              echo "environment=dev"                       >> $GITHUB_OUTPUT
              echo "image_tag=dev"                          >> $GITHUB_OUTPUT
              echo "deploy_path=/home/apps/pmis-web-dev"     >> $GITHUB_OUTPUT
              ;;
            refs/heads/staging)
              echo "environment=staging"                   >> $GITHUB_OUTPUT
              echo "image_tag=staging"                      >> $GITHUB_OUTPUT
              echo "deploy_path=/home/apps/pmis-web-staging" >> $GITHUB_OUTPUT
              ;;
            refs/heads/main)
              echo "environment=production"                >> $GITHUB_OUTPUT
              echo "image_tag=prod"                         >> $GITHUB_OUTPUT
              echo "deploy_path=/home/apps/pmis-web-prod"    >> $GITHUB_OUTPUT
              ;;
          esac

  # ─────────────────────────────────────────────────────
  # 3. Call the reusable deploy workflow
  # ─────────────────────────────────────────────────────
  deploy:
    name: Deploy
    needs: resolve-env
    permissions:
      contents: read
      packages: write
    uses: ./.github/workflows/deploy.yml
    with:
      environment: ${{ needs.resolve-env.outputs.environment }}
      image_tag:   ${{ needs.resolve-env.outputs.image_tag }}
      deploy_path: ${{ needs.resolve-env.outputs.deploy_path }}
      head_sha:    ${{ github.sha }}
    secrets: inherit

Notes on the caller:

success() in the resolve-env guard already means every job in needs passed, so a
separate "conclusion == success" check is redundant. The contains(fromJSON(...))
check ensures the pipeline only fires on the three intended branches and skips cleanly
on anything else. secrets: inherit forwards all repository and the resolved
environment's secrets into the called workflow — without it the reusable workflow sees
no secrets at all.

Passing head_sha: ${{ github.sha }} and having the reusable workflow check that exact
commit out guarantees you build precisely what Sonar validated, not whatever happens to
be at the branch tip when the deploy job starts.

7. The reusable deploy workflow (the engine)

Four jobs run in sequence: audit dependencies, build and push the image, scan the
pushed image, then deploy over SSH. The deploy job is bound to the resolved
Environment, which is what activates per-environment secrets and the production
approval gate.

name: Deploy PMIS Web

on:
  workflow_call:
    inputs:
      environment:
        description: "Target environment (dev | staging | production)"
        required: true
        type: string
      image_tag:
        description: "Image tag to build, push, and deploy"
        required: true
        type: string
      deploy_path:
        description: "Absolute path to the compose project on the server"
        required: true
        type: string
      head_sha:
        description: "Commit SHA to build and deploy"
        required: true
        type: string
      audit_level:
        description: "npm audit failure threshold"
        required: false
        type: string
        default: high

env:
  REGISTRY: ghcr.io

concurrency:
  group: deploy-pmis-web-${{ inputs.environment }}
  cancel-in-progress: false

jobs:
  # ─────────────────────────────────────────────────────
  # 1. Dependency vulnerability check
  # ─────────────────────────────────────────────────────
  dependency-check:
    name: Dependency Vulnerability Check
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ inputs.head_sha }}
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Audit dependencies
        run: npm audit --audit-level=${{ inputs.audit_level }}

  # ─────────────────────────────────────────────────────
  # 2. Build the image in CI and push to GHCR
  # ─────────────────────────────────────────────────────
  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 }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ inputs.head_sha }}

      - name: Set lowercase image name
        id: image-name
        run: |
          echo "image=ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to GitHub Container Registry
        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=${{ inputs.image_tag }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          build-args: |
            NEXT_PUBLIC_API_URL=${{ secrets.NEXT_PUBLIC_API_URL }}

  # ─────────────────────────────────────────────────────
  # 3. Scan the pushed image for OS / package CVEs
  # ─────────────────────────────────────────────────────
  image-scan:
    name: Container Security Scan
    needs: build-and-push
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      packages: read
    steps:
      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ needs.build-and-push.outputs.image }}:${{ inputs.image_tag }}
          severity: CRITICAL,HIGH
          exit-code: '1'
          ignore-unfixed: true

  # ─────────────────────────────────────────────────────
  # 4. Pull the pre-built image on the server and restart
  # ─────────────────────────────────────────────────────
  deploy:
    name: Deploy to Server
    needs: [build-and-push, image-scan]
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: ${{ inputs.environment }}   # activates env secrets + approval gate
    steps:
      - name: Deploy to Server via SSH
        uses: appleboy/ssh-action@v1.2.5
        env:
          GHCR_TOKEN:  ${{ secrets.GHCR_TOKEN }}
          IMAGE:       ${{ needs.build-and-push.outputs.image }}
          IMAGE_TAG:   ${{ inputs.image_tag }}
          DEPLOY_PATH: ${{ inputs.deploy_path }}
        with:
          host:     ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key:      ${{ secrets.SERVER_SSH_KEY }}
          port:     22
          envs: GHCR_TOKEN,IMAGE,IMAGE_TAG,DEPLOY_PATH
          script: |
            echo "$GHCR_TOKEN" | docker login ghcr.io -u ${{ secrets.GHCR_USERNAME }} --password-stdin
            docker pull "$IMAGE:$IMAGE_TAG"
            cd "$DEPLOY_PATH"
            docker compose -f docker-compose.yml down --remove-orphans
            docker compose -f docker-compose.yml up -d
            docker image prune -f

8. Design decisions worth understanding

Build once, deploy the artifact. The image is built and pushed in CI, and the
server merely pulls a pre-built tag. The server never runs docker build, so a deploy
is fast and reproducible, and a broken build can never leave a half-built container on
the box.

Scan before deploy, not after. The Trivy step sits between build and deploy with
exit-code: '1' on CRITICAL/HIGH findings, so a vulnerable image is blocked from ever
reaching a server. ignore-unfixed: true prevents the gate from failing on CVEs that
have no available fix — tune this to your risk tolerance.

The image tag must actually exist. A subtle, common bug: metadata-action here
emits a sha-<sha> tag and the environment tag (dev/staging/prod). If a later
step references a tag that was never produced — for example hardcoding :dev while the
metadata block only outputs latest — the scan and the server pull both fail on a
missing tag. This workflow avoids that by driving both the metadata type=raw tag and
the pull/scan references from the same inputs.image_tag.

Build args must match the Dockerfile. The build passes
NEXT_PUBLIC_API_URL=${{ secrets.NEXT_PUBLIC_API_URL }}. This only takes effect if the
Dockerfile declares a matching ARG NEXT_PUBLIC_API_URL. A mismatch between the arg
name here and the ARG in the Dockerfile is silent — the value simply never reaches
the build. Verify the names line up. (This is a frequent source of "the env var is
empty in the built app" confusion.)

Concurrency is per-environment. group: deploy-pmis-web-${{ inputs.environment }}
means a dev deploy and a prod deploy can run at the same time, but two deploys to the
same environment queue rather than clobber each other. cancel-in-progress: false
lets an in-flight deploy finish rather than being killed mid-way.

Quoting in the SSH script. Values are passed through envs: and referenced as
shell variables ($IMAGE, $DEPLOY_PATH) with quotes, rather than interpolated
directly into the script body. This avoids word-splitting and injection surprises if a
value ever contains unexpected characters.

9. Setup checklist

Create the three Environments (dev, staging, production) and add required reviewers to production.
Add the per-environment secrets to each environment and the shared SONAR_* secrets at the repository level.
Confirm the Dockerfile declares every ARG the build passes (NEXT_PUBLIC_API_URL, plus any others you add).
Ensure the compose project exists at the mapped path on each server (/home/apps/pmis-web-{dev,staging,prod}), with a docker-compose.yml that references the image and tag being pushed.
Confirm the deploy user on each server has permission to run docker and pull from GHCR (the GHCR_TOKEN needs read:packages).
Commit both workflow files. The quality workflow triggers on push to any of the three branches; because the deploy workflow is called via workflow_call, it does not need to exist on the default branch.

10. Adding a manual (on-demand) deploy path

To deploy an arbitrary branch to any environment on demand — useful for hotfixes or
re-deploys — add a workflow_dispatch trigger to the caller and hand its inputs to
the same reusable workflow. Add alongside the existing on: push: block:

on:
  push:
    branches: [develop, staging, main]
  workflow_dispatch:
    inputs:
      environment:
        description: "Environment to deploy"
        required: true
        type: choice
        options: [dev, staging, production]

Then branch the resolver on github.event_name: for a manual run, read
github.event.inputs.environment and derive the tag and path from it; for a push,
use the branch mapping as before. The reusable deploy.yml needs no changes — it only
ever sees resolved inputs.

Remember: dispatching a workflow via the API/UI requires the file to exist on the
default branch. If you want the manual path but cannot touch the default branch, keep
the dispatch trigger on the caller (the quality workflow) and let it call the reusable
deploy — the caller is what needs to be dispatchable, and the reusable file stays
resolved from the caller's ref.

11. Troubleshooting

Nothing runs after the quality gate passes.
Check that the quality workflow actually triggers on push to the branch in question,
and that the resolver's branch guard includes it. If you migrated from workflow_run,
confirm you removed all github.event.workflow_run.* references — they are null
outside a workflow_run event and will cause guarded jobs to skip.

The deploy job is skipped even though build succeeded.
github.ref is refs/heads/<branch> only on a push event. On a pull request it is a
merge ref, so a github.ref == 'refs/heads/develop' style guard is false. Deploy on
push, not PR.

docker pull fails on the server with a missing tag.
The tag referenced at deploy time was never produced at build time. Ensure the
type=raw,value=<tag> in the metadata step matches the tag used in the scan and pull
steps — drive both from a single input.

The built app has empty public env vars.
The build-arg name does not match the Dockerfile ARG, so the value never reaches the
build. Align the names exactly.

Production deploys without waiting for approval.
The deploy job is missing environment: production, or the production environment has
no required reviewers configured. The pause comes from the Environment protection rule,
not from anything in the YAML beyond binding the job to that environment.

A reusable-workflow deploy sees no secrets.
The caller is missing secrets: inherit (or an explicit secrets: block). Called
workflows do not inherit secrets automatically.

Ditch GHCR: A Production-Grade Self-Hosted Docker Registry on a Single DigitalOcean Droplet

FOLASAYO SAMUEL OLAYEMI — Mon, 27 Jul 2026 11:00:12 +0000

If you have ever hit the wall on a hosted registry's free private tier a 500 MB cap here, a per-seat charge there and you already run your own servers, there is a question worth asking: why not host the registry yourself?

The registry software is not the scary part. registry:2 is the CNCF Distribution project, the same reference implementation that sits underneath most managed registries. Harbor wraps it. Several big managed registries are built on it. It is boring, battle-tested, and idles at well under 50 MB of RAM.

What separates a hobby setup from a production one is everything around the binary: durable storage, TLS, authentication on both push and pull, garbage collection, and not leaving a naked port open to the internet. This article walks through a setup that gets all of that right, end to end, on a single droplet, with copy-paste commands you can follow start to finish.

By the end you will have:

A private registry running behind HTTPS on your own subdomain
Image layers stored in S3-compatible object storage (durable, effectively unbounded) instead of on the droplet's disk
A GitHub Actions pipeline that audits dependencies, builds, scans for CVEs, pushes, and deploys
Automatic garbage collection so the storage does not grow forever

Everything below uses placeholder names swap in your own domain, bucket, and paths.

The architecture

The single most common self-hosted registry mistake is publishing port 5000 to 0.0.0.0. That binds to every interface including the public one, so the whole thing sits open on the internet. We avoid that entirely.

Because most people fronting their containers already run Nginx Proxy Manager (NPM), the clean approach is:

The registry container joins the same Docker network as NPM and is reachable only by its container name no public host port.
NPM handles TLS and proxying. It requests the Let's Encrypt certificate and terminates HTTPS.
The registry handles its own authentication via an htpasswd file. This is deliberate: if both NPM (via an Access List) and the registry tried to own the Authorization header, you would get duplicate-header conflicts. Letting the registry own auth keeps that clean.
Object storage is the backend. Local disk on one droplet is a single point of failure and fills up. Pointing the registry at an S3-compatible bucket gives durability and room to grow without touching the disk.

[GitHub Actions]  --push over HTTPS-->  [NPM : TLS]  -->  [registry container]  -->  [S3-compatible object storage]
                                                                  ^
[Droplet deploy]  --pull over HTTPS----------------------------- /

The registry port is never exposed. NPM is the only thing that talks to it, and it does so over the internal Docker network.

Prerequisites

A droplet running Docker and Nginx Proxy Manager
A DNS A record registry.yourdomain.com → your droplet's public IP
An S3-compatible object storage bucket (DigitalOcean Spaces works well here since the registry ships with a native S3 driver) plus an access key / secret pair
Your cloud firewall allowing only ports 80, 443, and 22 and not 5000

Step 1: Find your NPM Docker network

Everything hangs off getting the network name right, so grab it first:

docker network ls | grep -iE 'proxy|npm'

Note the name it prints. Wherever you see npm-network below, substitute yours.

Step 2: The registry compose file

Create /home/apps/registry/docker-compose.yml:

services:
  registry:
    image: registry:2
    container_name: registry
    restart: always
    networks:
      - npm-network
    ports:
      - "127.0.0.1:5000:5000"     # localhost only, for on-server curl tests; NPM reaches it via the network, not this
    environment:
      REGISTRY_HTTP_SECRET: "${REGISTRY_HTTP_SECRET}"
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Private Registry"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_STORAGE_DELETE_ENABLED: "true"     # required for garbage collection to reclaim space
      REGISTRY_STORAGE: s3
      REGISTRY_STORAGE_S3_REGION: us-east-1        # dummy value; some S3-compatible providers ignore it but the driver requires it
      REGISTRY_STORAGE_S3_REGIONENDPOINT: https://nyc3.digitaloceanspaces.com
      REGISTRY_STORAGE_S3_BUCKET: your-registry-bucket
      REGISTRY_STORAGE_S3_ACCESSKEY: "${SPACES_KEY}"
      REGISTRY_STORAGE_S3_SECRETKEY: "${SPACES_SECRET}"
      REGISTRY_STORAGE_S3_SECURE: "true"
      REGISTRY_STORAGE_S3_FORCEPATHSTYLE: "true"   # safest with Spaces-style endpoints (avoids vhost/SNI cert issues)
    volumes:
      - ./auth:/auth:ro
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  npm-network:
    external: true

A few of these lines matter more than they look:

REGISTRY_STORAGE_DELETE_ENABLED: "true" without this, garbage collection cannot reclaim anything. The registry will happily grow forever.
REGISTRY_STORAGE_S3_FORCEPATHSTYLE: "true" path-style requests avoid the virtual-host / SNI certificate mismatches you can hit with some S3-compatible endpoints.
The bind is 127.0.0.1:5000:5000, not 5000:5000. That published port exists only so you can curl the registry locally for testing. NPM does not use it — it reaches the container over the Docker network by name.

Prefer to start on local disk? Delete every REGISTRY_STORAGE_S3_* line and the REGISTRY_STORAGE: s3 line, then add - ./data:/var/lib/registry under volumes. You can migrate to object storage later without changing anything else.

Step 3: Bring it up on the server

Paste this block. Edit the storage keys in the generated .env afterward.

mkdir -p /home/apps/registry/auth && cd /home/apps/registry

# create the .env (edit the storage keys after)
cat > .env <<EOF
REGISTRY_HTTP_SECRET=$(openssl rand -hex 32)
SPACES_KEY=your_access_key
SPACES_SECRET=your_secret_key
EOF

# basic-auth user — bcrypt (-B) is mandatory for the registry's htpasswd
sudo apt-get install -y apache2-utils
htpasswd -Bc /home/apps/registry/auth/htpasswd ci-pusher    # prompts for a password -> this becomes REGISTRY_PASSWORD

docker compose up -d
docker compose logs --tail=20 registry

The password you set for ci-pusher is what GitHub Actions and your server will use to log in. Keep it handy.

Step 4: Configure Nginx Proxy Manager

In the NPM UI:

Hosts → Proxy Hosts → Add Proxy Host

Domain Names: registry.yourdomain.com
Scheme: http
Forward Hostname: registry (the container name)
Forward Port: 5000
Block Common Exploits: on
Websockets Support: off

SSL tab

SSL Certificate: Request a new SSL Certificate
Force SSL: on
HTTP/2 Support: on
Agree to the Let's Encrypt terms, then Save.

Advanced tab: paste exactly this, and nothing else:

client_max_body_size 0;

That one directive is non-negotiable. NPM's default request body cap is around 1 MB, and image layers are far bigger, without lifting the cap, pushes fail with HTTP 413 Request Entity Too Large. Resist the urge to also paste proxy_set_header lines here; NPM already sets them, and adding duplicates is exactly what causes header conflicts.

Step 5: Smoke test

From the server:

curl -u ci-pusher:YOURPASS https://registry.yourdomain.com/v2/_catalog

Then a full round trip from your laptop:

docker login registry.yourdomain.com -u ci-pusher
docker pull hello-world
docker tag hello-world registry.yourdomain.com/test:1
docker push registry.yourdomain.com/test:1

If the push succeeds, TLS, auth, the body-size cap, and object storage are all working together. Double-check the cloud firewall still exposes only 80, 443, and 22.

Step 6: The GitHub Actions pipeline

This is a four-stage pipeline: audit dependencies, build and push, scan the pushed image for CVEs, then deploy over SSH. It assumes an upstream quality-check workflow triggers it, but you can change the trigger to a plain push on main if you prefer.

Add two repository secrets first (Settings → Secrets and variables → Actions):

REGISTRY_USERNAME = ci-pusher
REGISTRY_PASSWORD = the password you set for that user

You will also need the usual deploy secrets: SERVER_IP, SERVER_USER, and SERVER_SSH_KEY.

name: Build and Deploy
on:
  workflow_run:
    workflows: ["CodeQuality Checks"]
    types:
      - completed
    branches:
      - main
env:
  REGISTRY: registry.yourdomain.com
concurrency:
  group: deploy-web
  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
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Audit dependencies
        run: npm audit --audit-level=high

  build-and-push:
    name: Build & Push Image
    needs: dependency-check
    runs-on: ubuntu-latest
    timeout-minutes: 20
    outputs:
      image: ${{ steps.image-name.outputs.image }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
      - name: Set image name
        id: image-name
        run: echo "image=${{ env.REGISTRY }}/web-app" >> $GITHUB_OUTPUT
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      - name: Log in to registry
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}
      - 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}}
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          # Public client-side build vars are fine to bake in here.
          # Never pass real server-side secrets as build-args — they persist in image layers.
          build-args: |
            NEXT_PUBLIC_SOME_KEY=${{ secrets.NEXT_PUBLIC_SOME_KEY }}
            NEXT_PUBLIC_SOME_ID=${{ secrets.NEXT_PUBLIC_SOME_ID }}

  image-scan:
    name: Container Security Scan
    needs: build-and-push
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # pin the action by SHA
        env:
          TRIVY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
          TRIVY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
        with:
          image-ref: ${{ needs.build-and-push.outputs.image }}:latest
          severity: CRITICAL,HIGH
          exit-code: '1'
          ignore-unfixed: true

  deploy:
    name: Deploy to Server
    runs-on: ubuntu-latest
    needs: [build-and-push, image-scan]
    timeout-minutes: 10
    steps:
      - name: Deploy to Server via SSH
        uses: appleboy/ssh-action@v1.2.5
        env:
          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          envs: REGISTRY_PASSWORD
          script: |
            echo "$REGISTRY_PASSWORD" | docker login registry.yourdomain.com -u ${{ secrets.REGISTRY_USERNAME }} --password-stdin
            cd /home/apps/web-app
            docker compose -f docker-compose.yml pull
            docker compose -f docker-compose.yml up -d --remove-orphans
            docker image prune -f

Two things worth calling out because they trip people up on the migration away from a hosted registry:

The Trivy scan needs credentials. Your image is private now, so the scanner has to authenticate to pull it. That is what the TRIVY_USERNAME / TRIVY_PASSWORD env vars are for. Forgetting them produces a confusing "manifest unknown" style failure.

No more packages: write permissions block. Those scopes existed to let the built-in token push to the hosted registry. Talking to your own registry uses your REGISTRY_USERNAME / REGISTRY_PASSWORD secrets instead, so those permission blocks are dead weight and can go.

Also note the deploy step relies on docker compose pull plus pull_policy: always rather than a standalone docker pull. Doing it in one place removes a whole class of "the compose file and the pipeline disagree about which tag to run" bugs.

Step 7: The application compose file

On the server, the app's docker-compose.yml only needs its image line pointed at the new registry:

services:
  web-app:
    image: registry.yourdomain.com/web-app:latest
    pull_policy: always
    container_name: web-app
    ports:
      - "${HOST_PORT:-3000}:3000"
    restart: unless-stopped
    env_file:
      - .env
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

One nice optimization: add a hosts entry so the server resolves the registry domain to itself instead of hairpinning out to the public IP and back. TLS still validates because the SNI name matches the certificate.

echo "127.0.0.1 registry.yourdomain.com" | sudo tee -a /etc/hosts

Step 8: Garbage collection

Nothing reclaims disk (or object storage) automatically. Deleting a tag only removes the reference; the underlying blobs linger until you sweep them. Schedule that sweep:

sudo tee /etc/cron.d/registry-gc >/dev/null <<'EOF'
30 3 * * 0 root docker exec registry bin/registry garbage-collect --delete-untagged /etc/docker/registry/config.yml
EOF

That runs every Sunday at 03:30. One important caveat: garbage collection can delete a blob that an in-flight push is depending on, corrupting that push. Running it in a quiet window is the simple mitigation. If you ever push around the clock, put the registry into read-only mode for the duration of the sweep instead set REGISTRY_STORAGE_MAINTENANCE_READONLY_ENABLED=true, run GC, then flip it back.

Where this stops being enough

Bare Distribution deliberately does not do a few things that larger organizations eventually want: image signing and policy enforcement, team-level RBAC, cross-region replication, a web UI, and audit logs. If you need those, the move is not to abandon self-hosting it is to run Harbor, which is itself self-hosted and CNCF-graduated. It bundles its own registry, database, and vulnerability scanner, and realistically wants a couple of gigabytes of RAM and more moving parts.

For a single-organization setup with a handful of projects, though, registry:2 + object storage + auth + scheduled GC is a completely legitimate production answer. The registry engine is the same one the big players use; whether your deployment is production-grade comes down to the three things this guide made sure to cover durable storage, TLS with authentication, and garbage collection.

A couple of upgrades to consider

Pin deploys to the immutable SHA tag. latest is ambiguous and makes rollbacks guesswork. The pipeline above already produces a sha-<commit> tag on every build passing that SHA through to the compose image: line gives you deterministic, reversible deploys. When something breaks, you redeploy the previous SHA instead of hoping latest still points where you think it does.

Ship the registry's logs to wherever your other logs live. If you already run a log-aggregation stack, point a collector at the registry container so pushes, pulls, and GC runs show up alongside everything else. A registry is quiet right up until it is not, and having its logs where you already look saves you a bad afternoon.

Wrapping up

The takeaway is that "self-hosted registry" and "what serious infrastructure uses" are not opposite ends of a spectrum they share the same core. The gap is entirely operational, and it is a gap you can close in an afternoon: bind to localhost, let a reverse proxy own TLS, authenticate both directions, put the bytes in durable storage, and sweep the garbage on a schedule.

Do that, and you have a private registry that costs you nothing beyond the storage you actually use, lives next to the servers that pull from it, and answers to no one else's free-tier limits.

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

DEV Community: FOLASAYO SAMUEL OLAYEMI

How to Give a Linux User Scoped Access to a Specific Docker Container

How to Give a Linux User Scoped Access to a Specific Docker Container (Without Exposing the Entire Server)

How to Give a Linux User Scoped Access to a Specific Docker Container (Without Exposing the Entire Server)

The Setup

Step 1: Check If the User Already Exists

Step 2: Check the User's Current Groups

Step 3: Add the User to the Docker Group

Step 4: Create a Restricted Login Shell

Step 5: Set the Restricted Shell as the User's Login Shell

Step 6: Give the User Visibility Into the App Directory

Step 7: Verify End to End

What Both Users Share

Understanding the Two Access Modes

Quick Reference: All Commands

Conclusion

Branch-Based CI/CD: Quality Gate to Multi-Environment Deploy with GitHub Actions

1. The problem this solves

2. The workflow_run trap (why the obvious approach fails silently)

3. Why a reusable workflow (workflow_call) is the right primitive

4. Architecture overview

5. Prerequisites: GitHub Environments

6. The quality-gate workflow (the caller)

7. The reusable deploy workflow (the engine)

8. Design decisions worth understanding

9. Setup checklist

10. Adding a manual (on-demand) deploy path

11. Troubleshooting

Ditch GHCR: A Production-Grade Self-Hosted Docker Registry on a Single DigitalOcean Droplet

The architecture

Prerequisites

Step 1: Find your NPM Docker network

Step 2: The registry compose file

Step 3: Bring it up on the server

Step 4: Configure Nginx Proxy Manager

Step 5: Smoke test

Step 6: The GitHub Actions pipeline

Step 7: The application compose file

Step 8: Garbage collection

Where this stops being enough

A couple of upgrades to consider

Wrapping up

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)

2. The `workflow_run` trap (why the obvious approach fails silently)

3. Why a reusable workflow (`workflow_call`) is the right primitive

`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`)