DEV Community: FOLASAYO SAMUEL OLAYEMI

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

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

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

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

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

1. The mental model (read this first)

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

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

The flow, end to end:

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

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

2. Architecture of the running stack

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

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

Two ideas worth internalizing:

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

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

3. The Dockerfile

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

# syntax=docker/dockerfile:1

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

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

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

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

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

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

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

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

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

USER appuser

EXPOSE 4000 4001

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

Why each stage exists, in plain terms:

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

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

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

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

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

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

name: your-app

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

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

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

      GRANT CONNECT ON DATABASE appdb TO app_user, migrator_user;

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

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

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

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

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

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

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

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

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

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

volumes:
  postgres_data:
  redis_data:

networks:
  backend:
    driver: bridge

The parts that trip people up, explained

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

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

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

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

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

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

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

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

5. The secrets file: .env.example

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

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

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

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

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

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

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

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

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

name: CodeQuality Checks

on:
  push:
    branches:
      - main

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

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

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

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

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

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

name: Deploy

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

env:
  REGISTRY: ghcr.io

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

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

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

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

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

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

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

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

            cd "$DEPLOY_PATH"

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

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

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

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

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

Why the deploy job is shaped this way

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

8. Keeping dependencies fresh: dependabot.yml

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

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

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

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

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

9. Step-by-step: your first deploy

One-time setup

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

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

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

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

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

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

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

Every deploy after that

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

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

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

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

10. Common errors and how to fix them

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

"My edits to the server file keep reverting!"

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

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

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

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

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

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

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

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

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

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

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

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

Migration fails: `permission denied for database`

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

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

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

IGNORE_STARTUP_PARAMETERS: extra_float_digits,statement_timeout,lock_timeout,idle_in_transaction_session_timeout

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

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

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

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

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

The database "disappeared" after I renamed something

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

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

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

Dependabot: "security update not possible"

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

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

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

11. A pre-deploy checklist

Pin this somewhere:

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

12. Closing lessons

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

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

Happy shipping.

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

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

FOLASAYO SAMUEL OLAYEMI

Jun 24

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

#webdev #devops #tutorial #automation

6 min read

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

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

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

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

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

What We're Building

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

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

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

A Quick Word on Vagrant

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

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

The Complete Vagrantfile

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

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

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

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

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

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

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

      # Ensure hostname is configured persistently
      hostnamectl set-hostname db01

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

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

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

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

end

Breaking It Down

The configuration block

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

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

Defining multiple machines

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

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

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

Choosing a box

web01.vm.box = "ubuntu/focal64"

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

Setting the hostname

web01.vm.hostname = "web01"

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

Private networking

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

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

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

Provisioning the database node

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

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

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

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

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

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

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

Running the Lab

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

# Bring up all three machines
vagrant up

# SSH into any machine by name
vagrant ssh db01

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

# Check the status of every machine
vagrant status

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

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

Common Pitfalls

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

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

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

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

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

Where to Go Next

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

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

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

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

FOLASAYO SAMUEL OLAYEMI

Jun 23

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

#ai #devops #tutorial #programming

2 min read

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

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

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

fatal: Need to specify how to reconcile divergent branches

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

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

The Problem

A simple deployment script was running:

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

But it failed with:

fatal: Need to specify how to reconcile divergent branches

This stopped deployment completely.

What Git Was Telling Us

To understand the issue, we ran:

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

Output:

1       16

This means:

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

So the branches had diverged.

Why This Happens (Important)

This usually happens when:

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

Git refuses to guess whether you want to:

Merge
Rebase
Or reject changes

So it throws an error.

Deep Diagnosis

We inspected the commits:

git log --oneline origin/main..HEAD

Result:

6d9046b Merge pull request #222

Then:

git log --oneline HEAD..origin/main

Showed multiple new GitHub PR merges.

Conclusion:

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

The Real Fix (Production Safe)

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

Instead, use a deterministic reset:

git fetch origin
git reset --hard origin/main

Then redeploy:

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

Why This Works

This approach ensures:

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

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

The Broken Approach

Avoid this on servers:

git pull

Why?

Because it:

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

Best Practice Deployment Script

cd opt/yourprojectdirectory

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

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

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

echo "Deployment successful"

Key Lesson

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

Conclusion

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

Once you understand:

HEAD
origin/main
divergence

…you can fix it in under 30 seconds.

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

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

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

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

FOLASAYO SAMUEL OLAYEMI

Jun 13

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

#macos #chrome #troubleshooting #productivity

4 min read

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

FOLASAYO SAMUEL OLAYEMI — Sat, 13 Jun 2026 03:56:07 +0000

It is one of the most frustrating experiences in online learning: you sit down to focus on a Udemy course, but the video player constantly pauses, freezes, or refuses to load. Meanwhile, YouTube, Netflix, and every other app on your Mac run perfectly fine.
Because other platforms work without a hitch, it is easy to assume the issue lies with Udemy's servers. However, the root cause is usually a silent conflict between your browser settings, macOS security features, and Udemy’s strict digital rights management (DRM) protections.
If you are stuck on a looping loading wheel, here is exactly why it happens and how to fix it in less than two minutes.

Quick-Fix Troubleshooting Checklist

Save or screenshot this step-by-step breakdown to instantly diagnose and fix your playback issues:

Step 1: Open Chrome in Incognito Mode

Open a new Incognito window (Cmd + Shift + N on Mac).
Try playing the video again.

If it works:

Disable ad blockers.
Disable VPN privacy shields or browser extensions one at a time.

If it still fails:

Continue to Step 2.

Step 2: Disable Hardware Acceleration

Open Chrome.
Go to Settings → System.
Turn off Use graphics acceleration when available.
Relaunch Chrome.
Test the video again.

Step 3: Check Mac Security and Display Connections

Disconnect any external monitors or docking stations.
Close applications that may interfere with video playback:
- Zoom
- Discord
- OBS Studio
- Screen recording tools
Test video playback again.

Step 4: Clear Temporary Browser Data

Open Chrome.
Go to Settings → Privacy and Security → Clear Browsing Data.
Select:
- Cookies and other site data
- Cached images and files
Clear the data.
Restart Chrome and try again.

Still Not Working?

If the issue persists after completing all four steps:

Update Chrome to the latest version.
Update macOS.

The Main Culprit: Hardware Acceleration Conflict

The most common reason Udemy videos stutter or freeze on a Mac is a feature called Hardware Acceleration inside Google Chrome.

What is Hardware Acceleration?

By default, Chrome offloads heavy visual tasks—like rendering high-definition video or 3D graphics—to your Mac’s dedicated graphics card (GPU). While this sounds efficient, outdated graphics drivers or macOS switching glitches can cause the browser to conflict with Udemy’s encrypted player.

Is it safe to disable?

Yes. Turning off hardware acceleration simply instructs Chrome to process video playback using your Mac’s main processor (CPU) instead of the graphics card. Your data, extensions, and browser history remain completely safe, and you will not notice any performance drops for everyday browsing.

How to turn it off in Chrome:

Click the three vertical dots in the top-right corner of Chrome.
Select Settings from the dropdown menu.
Click on System in the left-hand sidebar.
Locate "Use graphics acceleration when available" and toggle the switch to Off.
Click the Relaunch button that appears next to the toggle to restart your browser.

Still Pausing? Check macOS Security and Extensions

If adjusting your graphics settings does not fully solve the issue, Udemy’s strict piracy-protection protocols might be actively halting your stream. Look out for these two common macOS triggers:

1. Background Screen Recording & Mirroring Apps

Udemy uses strict DRM to prevent users from recording copyrighted course material. Because of this, if macOS detects any active screen-capture or mirroring software, the Udemy player will instantly pause.

Close background apps like Zoom, Microsoft Teams, OBS, CleanShot X, or Discord before playing a video.
Disconnect from external monitors or docking stations temporarily to see if a hardware connection is triggering the block.

2. Corrupted Browser Cache or Ad-Blockers

Sometimes, aggressive browser extensions mistake Udemy’s security protocols for tracking scripts and block them entirely.

Try opening your course in a Chrome Incognito Window. If the video plays smoothly, a third-party extension (like an ad-blocker or VPN privacy shield) is causing the conflict. You will need to whitelist Udemy in that extension's settings.
Clear your browser's cached files and cookies to wipe out any corrupted temporary data holding back the player.

How to Turn Hardware Acceleration Back On Later

If you finish your course and want to re-enable your graphics card for heavy web tasks—like playing 3D browser games or editing complex graphics in Canva—you can turn it back on instantly.

Open Chrome and click the three vertical dots (top right).
Open Settings and click System.
Toggle the "Use graphics acceleration when available" switch back to On (it will turn blue).
Click Relaunch to apply the changes.

Tip: If Udemy starts pausing again after you turn it back on, it means your Mac's graphics card drivers need an update, or a background recording app is still running.

Summary

You do not have to let technical glitches derail your learning momentum. By simply toggling off hardware acceleration in Chrome and clearing out background recording apps, you can bypass macOS playback conflicts and get back to mastering your next skill.

If you found this useful, I create contents about DevOps, infrastructure, and backend engineering on YouTube, Hashnode and Dev.to. Follow along if this is the kind of problem-solving you want more of.

Fixing GHCR “Unauthorized” + Docker “Cannot perform interactive login from non-TTY” in GitHub Actions + SSH Deployments

FOLASAYO SAMUEL OLAYEMI — Thu, 11 Jun 2026 22:48:42 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 11

Fixing GHCR “Unauthorized” + Docker “Cannot perform interactive login from non-TTY” in GitHub Actions + SSH Deployments

#devops #infrastructure #ai #tutorial

3 min read

Fixing GHCR “Unauthorized” + Docker “Cannot perform interactive login from non-TTY” in GitHub Actions + SSH Deployments

FOLASAYO SAMUEL OLAYEMI — Thu, 11 Jun 2026 22:47:58 +0000

When deploying applications using GitHub Actions + SSH (appleboy/ssh-action) and pulling images from GitHub Container Registry (GHCR), two common errors often appear together:

unauthorized when pulling Docker images from GHCR
Cannot perform an interactive login from a non TTY device

These errors usually look confusing, but they both come from the same root issue: Docker authentication is not correctly handled in a non-interactive environment (CI/CD or SSH automation).

This article explains what is happening, why it fails, and how to fix it permanently.

The Problem (What You See in Logs)

1. GHCR Unauthorized Error

Error response from daemon:
Head "https://ghcr.io/v2/ORG/REPO/manifests/latest": unauthorized

This means Docker tried to pull a private image from GHCR but was not authenticated.

2. Non-TTY Login Error

Error: Cannot perform an interactive login from a non TTY device

This means Docker tried to run:

docker login ghcr.io

But failed because:

GitHub Actions and SSH scripts do not support interactive input (no terminal to type username/password).

Root Cause

Both errors come from the same issue:

Docker login is either:

Missing entirely ❌
Or written in interactive mode ❌
Or not receiving credentials correctly ❌

In CI/CD environments:

There is no keyboard input
There is no terminal (TTY)
Everything must be fully automated

Correct Mental Model

Think of GHCR like a private building:

docker pull = trying to enter the building
docker login = showing your ID card

If you don’t show your ID before entering, you get:

❌ unauthorized

If you try to “type your password manually” in automation:

❌ non-TTY error

Correct Fix (Production-Ready Solution)

Step 1: Create a GitHub Token (PAT)

Go to:

GitHub → Settings → Developer Settings → Personal Access Tokens

Create a token with:

read:packages ✅
repo (if private repo) ✅

Step 2: Store Secrets in GitHub Actions

Add these secrets:

GHCR_USERNAME → your GitHub username
GHCR_TOKEN → your personal access token

Step 3: Pass Secrets into SSH Action

In your GitHub Actions workflow:

- name: Deploy via SSH
  uses: appleboy/ssh-action@v1.2.5
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USER }}
    key: ${{ secrets.SSH_KEY }}
    envs: GHCR_USERNAME,GHCR_TOKEN
    script: |
      echo $GHCR_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin
      docker compose pull
      docker compose up -d

Step 4: Use Non-Interactive Docker Login (IMPORTANT)

✔️ Correct way:

echo $GHCR_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin

Wrong way (causes TTY error):

docker login ghcr.io

Step 5: Verify Login on Server

Run:

cat ~/.docker/config.json

If login worked, you should see:

"auths": {
  "ghcr.io": {
    "auth": "..."
  }
}

Final Deployment Flow (Correct Order)

Your SSH deployment script should always follow this pattern:

set -e

echo "Logging into GHCR..."
echo $GHCR_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin

echo "Pulling latest images..."
docker compose pull

echo "Restarting containers..."
docker compose up -d

echo "Cleaning unused images..."
docker system prune -f

Common Mistakes That Cause This Issue

1. Using interactive login

docker login ghcr.io

❌ Breaks in CI/CD

2. Forgetting to pass environment variables into SSH

If you don’t include:

envs: GHCR_TOKEN,GHCR_USERNAME

Then the server receives empty values → login fails silently.

3. Using wrong image name or tag

Example:

ghcr.io/org/repo:latest

Make sure:

Image exists
Tag exists (latest or versioned tag)

4. Missing package permissions

Your token must have:

read:packages

Otherwise GHCR will always return unauthorized.

Why This Only Happens in DevOps Automation

This issue is extremely common in:

GitHub Actions
Docker CI/CD pipelines
SSH deployment scripts
Kubernetes init containers

Because all of them are:

Non-interactive environments (no human input allowed)

Summary

If you remember only one thing:

❗ GHCR pull failures in CI/CD = ALWAYS authentication problem

And:

unauthorized → no valid login
non-TTY login error → you used interactive login incorrectly

Final Working Checklist

✔ Use docker login --password-stdin
✔ Pass secrets into SSH (envs:)
✔ Ensure token has read:packages
✔ Ensure image exists in GHCR
✔ Avoid interactive commands in CI/CD

How I Recovered 35GB on a Production Server by Moving Docker Builds Off It

FOLASAYO SAMUEL OLAYEMI — Thu, 11 Jun 2026 10:37:28 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 11

How I Recovered 35GB on a Production Server by Moving Docker Builds Off It

#devops #infrastructure #productivity #tutorial

7 min read

How I Recovered 35GB on a Production Server by Moving Docker Builds Off It

FOLASAYO SAMUEL OLAYEMI — Thu, 11 Jun 2026 10:37:06 +0000

And why your server should never be your build machine

It started with a simple task, deploy a new service on a DigitalOcean droplet already running a dozen containerized apps. But the moment I SSHed in, the MOTD stopped me cold:

Usage of /: 100.0% of 154.88GB

100%. Not 92%. Not "you should look at this soon." A hundred percent. On a production server running over a dozen live services.

This is the story of how I diagnosed it, fixed it surgically without touching a single running service, and more importantly, how I changed the architectural pattern that caused it in the first place.

First, Understand the Terrain

Before running a single cleanup command, I did what every senior engineer does when something is wrong in production: I measured everything first.

docker system df -v

This is the command that tells you the truth. Not df -h alone, not vibes this. It breaks down exactly how Docker is consuming your disk: images, containers, volumes, and build cache, with per-item detail.

Here's what came back:

Images space usage:     ~8GB total
Containers space usage: ~50MB
Local Volumes:          ~4.1GB (two anonymous volumes with 0 links)
Build cache usage:      29.22GB

The containers themselves? Barely anything. The images? Manageable. The build cache? 29.22 gigabytes.

That single number told me everything I needed to know about what had been happening on this server.

What Is Docker Build Cache and Why Does It Silently Destroy You?

When Docker builds an image, it executes your Dockerfile instruction by instruction. Each instruction RUN, COPY, FROM produces a layer. Docker is smart: if a layer hasn't changed since the last build, it reuses the cached version instead of recomputing it.

This is what makes docker build fast on a developer machine or a CI runner. First build is slow. Second build? Docker says "I've seen this before" and skips to the parts that changed.

But here's the part nobody talks about enough: that cache lives on disk. Permanently. Until you explicitly remove it.

Every build you run on a server adds to it. Every time you push a new image and Docker re-resolves your base image layers, it caches them. Rebuild with a new Node.js version? Cached. Pull a new ubuntu:24.04? Cached. Run npm install after updating package.json? Every intermediate layer: cached.

Over weeks of active development across 10+ services, all building on the same server, you accumulate layers on top of layers, most of them orphaned by subsequent builds, none of them cleaned up automatically.

This is exactly what happened here. 29GB of silent accumulation.

The Deeper Problem: Your Server Is Not a Build Machine

When you build Docker images directly on the server that runs them, you are asking one machine to do two fundamentally different jobs simultaneously:

Job 1: Build environment, Compile code, resolve dependencies, execute multi-stage builds, cache intermediate layers, pull base images from registries.

Job 2: Runtime environment, Run containers reliably, serve real traffic, maintain uptime, stay lean and predictable.

These two jobs have opposing requirements.

A build environment benefits from cache, the more it stores, the faster subsequent builds are. A runtime environment suffers from cache, it's dead weight that grows without bound and competes with your running services for the disk space they need to function.

Putting both on the same machine is a design smell. It works, until it doesn't. And when it breaks, it breaks at 100% disk utilisation, which means everything on that machine is now at risk.

The Senior Move: Eliminate the Source, Not Just the Symptom

The junior response to this situation is: "Run docker builder prune and move on."

That would have recovered the 29GB. But three weeks later, the same builds would have filled it back up. You'd be doing this every month. Reactive. Whack-a-mole.

The senior response is: "Why is this cache here in the first place, and how do I make sure it can never accumulate to this scale again?"

The answer: move the build off the server entirely.

For one of our Next.js services, I set up a GitHub Actions pipeline that:

Builds the Docker image in the CI runner (GitHub's infrastructure, not yours)
Pushes the built image to GHCR (GitHub Container Registry)
SSHes into the droplet and runs docker compose pull && docker compose up -d

The server never runs docker build. It only ever runs docker pull and docker run. It is a runtime environment again, which is exactly what it should be.

The docker-compose.yml reflects this cleanly:

services:
  web-app:
    image: ghcr.io/your-org/your-app:latest
    container_name: web-app
    ports:
      - "4700:4700"
    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://127.0.0.1:4700"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

No build: key. No context:. No Dockerfile reference. The server simply pulls a pre-built, verified image from the registry and runs it. The build machine (GitHub Actions runner) does the heavy lifting and discards its own cache after each job. The server's disk never sees a single build layer.

The Cleanup — Surgical, Not Nuclear

Once I had the architectural change in place, I cleaned up what had accumulated. The key here was being deliberate about what I removed and what I left alone. There are over a dozen services running on this server. The wrong command would have meant downtime.

Here's the actual order of operations:

Step 1: Build cache the biggest win, zero risk

docker builder prune -f

This removes only the build cache. It touches nothing else, no running containers, no images, no volumes. Every service kept running. Freed: 29.22GB.

Worth understanding: the next time each remaining server-built service rebuilds, it will be slightly slower because the cache is gone. That's the only consequence. After the first post-prune build, cache starts accumulating again and speed returns.

Step 2: Journal logs the second biggest win

journalctl --vacuum-time=3d

The journald logs had grown to 4.0GB. This command keeps the last 3 days and removes everything older. No service is affected logs are still being written, you're just trimming history.

Step 3: The old local image the obvious orphan

docker rmi your-app-local:latest

docker system df -v showed a locally-built image consuming 1.554GB with 0 running containers. This was the artifact from the old way, back when the server was still building the image locally. It was superseded the moment the pipeline took over and GHCR became the source of truth. Dead weight.

Step 4: Anonymous volumes, verify before you delete

Two anonymous volumes had 0 LINKS, meaning no container was referencing them. Before removing them, I inspected both:

docker inspect <volume-id>

Both came back with "Containers": {}. Orphaned. Removed. Another ~4GB recovered.

What I Did Not Touch

This is equally important.

docker system prune -a, not run. The -a flag removes ALL images not currently attached to a running container. Several services on this server are temporarily stopped but need their images intact for restart. This command would have deleted them.
docker volume prune, not run blindly. I inspected volumes individually first. One wrong deletion here and you're restoring a database from backup at 11pm.
Any running container, untouched throughout. Before and after, all services remained up.

The discipline of knowing what not to run matters as much as knowing what to run.

The Numbers

Cleanup action	Space recovered
Build cache (`docker builder prune -f`)	29.22GB
Journal logs (`journalctl --vacuum-time=3d`)	~4.0GB
Old local image (superseded by pipeline)	1.554GB
Orphaned anonymous volumes	~4.1GB
Total	~38GB

Disk utilisation dropped from 100% to roughly 75%, and more critically, the architectural change means the build-cache portion can never grow back to that scale for the migrated service.

Going Forward: Keep It From Happening Again

For services still building on the server (while I migrate them to pipeline builds), a weekly cron prevents silent accumulation:

# crontab -e
# Prune build cache older than 7 days, every Sunday at 3am
0 3 * * 0 docker builder prune --filter "until=168h" -f >> /var/log/docker-prune.log 2>&1

The --filter "until=168h" flag is the important detail here, it removes cache older than 7 days but preserves recent cache, so the next build isn't cold. It's maintenance, not surgery.

The real fix, though, is finishing the migration. Every service that moves to pipeline builds is a service whose build artefacts never touch the production server again. That's the direction everything is heading.

The Takeaway

If there's one principle to extract from all of this, it's this:

A production server's only job is to run containers. Any server that is also building containers is doing two jobs, and eventually, those jobs will conflict.

Build cache is invisible until it's not. It accumulates quietly, efficiently, and with the best of intentions, making your builds faster. But on a shared production server, it's borrowing disk space that belongs to your running services, and it will keep borrowing until there's nothing left.

The fix isn't a cleanup script on a cron job. It's a CI/CD pipeline that builds in an ephemeral environment, pushes to a registry, and lets your server do the one thing it's actually there to do.

Diagnose first. Operate surgically. Fix the root cause, not the symptom. And never let your server be its own build machine.

Spent hours trying to auto-post from Hashnode to Dev.to. RSS? Blocked. GraphQL API? Now paid. Proxy services? Also blocked. I documented every dead end + the fix that actually works by building a GitHub Actions workflow that syncs Hashnode to Dev.to

FOLASAYO SAMUEL OLAYEMI — Sun, 07 Jun 2026 12:24:36 +0000

FOLASAYO SAMUEL OLAYEMI

Jun 7

How to Auto-Sync Your Hashnode Blog to Dev.to Using GitHub Actions (2026 Guide)

#discuss #automation #tutorial #devops

5 min read

DEV Community: FOLASAYO SAMUEL OLAYEMI

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

1. The mental model (read this first)

2. Architecture of the running stack

3. The Dockerfile

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

The parts that trip people up, explained

5. The secrets file: .env.example

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

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

Why the deploy job is shaped this way

8. Keeping dependencies fresh: dependabot.yml

9. Step-by-step: your first deploy

One-time setup

Every deploy after that

10. Common errors and how to fix them

"My edits to the server file keep reverting!"

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

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

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

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

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

Migration fails: permission denied for database

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

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

The database "disappeared" after I renamed something

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

Dependabot: "security update not possible"

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

11. A pre-deploy checklist

12. Closing lessons

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.

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

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

What We're Building

A Quick Word on Vagrant

The Complete Vagrantfile

Breaking It Down

The configuration block

Defining multiple machines

Choosing a box

Setting the hostname

Private networking

Provisioning the database node

Running the Lab

Common Pitfalls

Where to Go Next

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

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

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

The Problem

What Git Was Telling Us

Why This Happens (Important)

Deep Diagnosis

The Real Fix (Production Safe)

Why This Works

The Broken Approach

Best Practice Deployment Script

Key Lesson

Conclusion

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

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

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

Quick-Fix Troubleshooting Checklist

Step 1: Open Chrome in Incognito Mode

Step 2: Disable Hardware Acceleration

Step 3: Check Mac Security and Display Connections

Step 4: Clear Temporary Browser Data

Still Not Working?

The Main Culprit: Hardware Acceleration Conflict

What is Hardware Acceleration?

Is it safe to disable?

How to turn it off in Chrome:

Still Pausing? Check macOS Security and Extensions

1. Background Screen Recording & Mirroring Apps

2. Corrupted Browser Cache or Ad-Blockers

How to Turn Hardware Acceleration Back On Later

Summary

Fixing GHCR “Unauthorized” + Docker “Cannot perform interactive login from non-TTY” in GitHub Actions + SSH Deployments

Fixing GHCR “Unauthorized” + Docker “Cannot perform interactive login from non-TTY” in GitHub Actions + SSH Deployments

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