How We Moved Docker Builds Off Our VPS

A pull-only Docker Compose pipeline with GitHub Actions, GHCR, and Dokploy — and why our server finally stopped fighting Next.js builds.

The Problem: Your App Server Shouldn’t Be a Build Server

For a long time, our deployment looked like this:

git push → Dokploy → yarn install → next build → docker build → deploy

↑ all on the same VPS

That works until it doesn’t.

Our stack is a large Next.js 16 app: hundreds of API routes, Supabase, heavy dependencies. Building on the VPS meant:

CPU spikes during yarn build and Docker layer creation
RAM pressure and OOM-killed builds
Disk growth from node_modules, build caches, and dangling images (we recovered ~10 GB from BuildKit alone)
Long deploys (15–20+ minutes, often cancelled)
Inconsistent builds — different cache state on the server vs local/CI

The server’s job is to run containers. Making it compile a monorepo-sized app on every deploy is the wrong split of responsibilities.

The New Approach: Build Remotely, Pull Locally

We inverted the model:

GitHub Actions → GHCR (registry) → Dokploy VPS

heavy artifact lightweight (pull + up)

Phase	Where	What Happens
Build	GitHub Actions	Multi-stage Docker build, BuildKit cache, env secrets injected
Publish	GHCR	Push tagged images (:release, :production, :sha-xxxxxxx)
Deploy	Dokploy	docker compose pull && up — no yarn, no next build on server
Route	Traefik (Dokploy)	Domain → container port

The VPS went from builder + runner to runner only.

Architecture in Practice (Gamms)

Branch Model

Branch	Purpose	Image Tag	Deploy Target
develop	Local dev + CI	(none on push)	—
release	Staging / UAT	:release	uat.gamms.app
production	Live	:production, :latest	gamms.app

Promotion flow: feature/* → PR → develop → PR → release → PR → production

What Runs on Every Merge

Docker Publish — build with environment-specific secrets, push to GHCR
Database Migrations — supabase db push to staging or production
Dokploy webhook — POST after successful push → pull + redeploy

Key Implementation Pieces

1. Slim Runtime Image (Multi-Stage Dockerfile)

The build stage is huge; the runtime image is not. We use Next.js standalone output on Alpine:

# Build stage: full node_modules + compile (discarded)

FROM node:22.13.0-bookworm-slim AS builder

RUN yarn build:skip-lint

# Runtime stage: only what runs in prod (~396 MB)

FROM node:22.13.0-alpine AS runner

COPY --from=builder /app/.next/standalone ./

COPY --from=builder /app/.next/static ./.next/static

COPY --from=builder /app/public ./public

CMD ["node", "server.js"]

Build-time secrets (e.g. NEXT_PUBLIC_*, service role for SSG) come from GitHub Environment secrets. Runtime-only secrets (API keys, webhooks) stay in Dokploy env — not baked into the image.

2. Pull-Only Compose for Dokploy

We keep two compose files:

docker-compose.yml — local dev, can build
docker-compose.dokploy.yml — production path, pull only

services:

service-name:

image: ${SERVICE_IMAGE:?Set SERVICE_IMAGE to your GHCR image tag}

pull_policy: always

ports:

- '${SERVICE_PORT:-3000}:3000'

environment:

ENV_VAR_NAME: ${ ENV_VAR_NAME:?required}

healthcheck:

test: ['CMD', 'node', '-e', "...GET /api/health..."]

Critical: Dokploy must use docker-compose.dokploy.yml, not the build-on-server file.

3. GitHub Actions Workflow

On push to release or production:

Checkout → Buildx → login to GHCR with GITHUB_TOKEN
Build with --secret for sensitive build args (not stored in layers)
Push tags: :release or :production + :latest + :sha-xxxxxxx
Trigger Dokploy webhook

Environment mapping:

release branch → GitHub Environment staging → image :release
production branch → GitHub Environment production → image :production

4. GHCR Authentication on the Server

GitHub Actions pushes with GITHUB_TOKEN. The VPS pulls with a separate credential:

echo '<CLASSIC_PAT>' | docker login ghcr.io -u <GITHUB_USER> --password-stdin

Use a classic PAT with read:packages (+ repo for private org packages). Fine-grained tokens often don’t cover Packages. Configure the same credentials in Dokploy’s registry settings if available.

5. Auto-Deploy via Webhook

After a successful push, CI POSTs to Dokploy:

curl -fsS -X POST "$DOKPLOY_DEPLOY_WEBHOOK_URL_STAGING" \

-H "Content-Type: application/json" \

-H "X-GitHub-Event: push" \

-d '{"ref":"refs/heads/release","repository":{"full_name":"ORG/repo"}}'

Store webhook URLs as repository secrets:

DOKPLOY_DEPLOY_WEBHOOK_URL_STAGING
DOKPLOY_DEPLOY_WEBHOOK_URL_PRODUCTION

Dokploy’s compose branch must match the webhook ref (e.g. release), or you get “Branch Not Match”.

Dokploy Gotchas We Hit (So You Don’t Have To)

Traefik 404 While the App Is Healthy

Symptom: https://your-domain/api/health returns 404, but direct IP works.

curl http://SERVER_IP:3005/api/health # 200 OK

curl https://your-domain/api/health # 404

Fix: In Dokploy domain settings, set Container port = 3000 (inside the container), not the host port (GAMMS_PORT=3005 maps 3005:3000).

How to Tell GHCR Pull vs Local Build

Source	Image Name on Server
GHCR pull	ghcr.io/org/repo:release
Dokploy local build	project-id-service:latest

If you see the second pattern, you’re still building on the server.

Disk Cleanup After Migration

Safe commands (won’t touch running containers):

docker container prune -f

docker image prune -f

docker buildx prune -a -f

# Remove orphaned buildkit volume if huge:

docker rm buildx_buildkit_builder-containerd0

docker volume rm buildx_buildkit_builder-containerd0_state

We reclaimed ~10 GB from an orphaned BuildKit volume alone.

Results

Metric	Before (Build on VPS)	After (GHCR Pull)
Deploy time on server	15–20+ min (often failed)	Seconds (pull + up)
Build location	VPS CPU/RAM	GitHub runners + cache
Runtime image size	Large / inconsistent	~396 MB (standalone)
Disk from build cache	10+ GB BuildKit volume	0 B build cache
Staging ↔ prod parity	Uncertain	Same pipeline, different tags
Rollback	Hard	Retag or pull :sha-xxxxxxx

Both UAT (uat.gamms.app) and production (gamms.app) now run the same pipeline with different GitHub Environment secrets and image tags.

Migration Checklist

Use this when moving any app (Next.js, Vite, Nest, etc.) to the same pattern:

Multi-stage Dockerfile with minimal runtime image
.github/workflows/docker-publish.yml → push to GHCR
GitHub Environments staging / production with build secrets
docker-compose.dokploy.yml with image: + pull_policy: always (no build:)
First successful GHA run → image visible under Packages
docker login ghcr.io on VPS (or Dokploy registry config)
Dokploy: compose path, branch, GAMMS_IMAGE=ghcr.io/...
Domain → container port (not host port)
Webhook URL → GitHub repository secret
Smoke test: /api/health, login, one critical flow
Prune old local-build images and BuildKit volume

When This Pattern Fits (and When It Doesn’t)

Great Fit

Large Node/Next/React apps that stress small VPSes
Multiple environments (staging + production) needing reproducible artifacts
Teams already on GitHub wanting cheap registry (GHCR included with GitHub)

Less Critical

Tiny static sites (nginx + 5 MB dist)
Apps that already build in CI and only deploy artifacts without Docker

Still Your Responsibility

Database migrations (we run supabase db push in a separate workflow)
Runtime secrets in Dokploy
Traefik/domain wiring
Package visibility and PAT rotation

Conclusion

Moving Docker builds from the VPS to GitHub Actions, publishing to GHCR, and pointing Docker Compose at pre-built images wasn’t a framework change — it was an operations change.

The server stopped compiling. Deploys got fast and boring. Disk stopped filling with build cache. Staging became a trustworthy preview of production.

If your PaaS or VPS is “building” your app on every deploy, ask one question: does this machine need to compile, or only run? For most production setups, the answer is run.