Fix Vercel & Cloudflare Deployment Failures with Coolify VPS & Docker: The Complete Production Handbook

The Root Cause: When Next.js executes next build, it analyzes the Abstract Syntax Tree (AST) of every page, creates chunk graphs, and concurrently executes generateStaticParams(). On small sites, V8 garbage collection manages this within 600MB. But when you exceed 50 pages or import heavy dependencies like icons, charts, or syntax highlighters, memory requirements exceed 1GB. Because Vercel's free tier enforces a 1024MB container cgroup limit, Node.js crashes.

The Root Cause: Cloudflare Pages uses V8 isolates rather than traditional Node.js virtual machines. While V8 isolates start in 5 milliseconds, they do NOT support Node.js native filesystem APIs, standard child processes, or C++ addons. Furthermore, the compiled JS bundle must fit within 1MB. If your site uses Prisma, bcrypt, or PDF generation, your bundle will exceed 3MB to 10MB, causing Cloudflare deployments to fail immediately.

The Root Cause: Course students building programmatic SEO websites (e.g. location pages, product directories, dictionary databases) often export 1,000+ paths in generateStaticParams(). On constrained serverless build workers with throttled CPU burst credits, each page takes 2-4 seconds to fetch database records and render HTML. Multiplying 1,500 pages by 2.5 seconds yields over 60 minutes of build time, exceeding Vercel's hard 45-minute cutoff.

The Root Cause: If you develop on a Mac (M1/M2/M3 Apple Silicon ARM64) or Windows x64 and commit your package-lock.json or node_modules without cross-compilation flags, the server runtime cannot execute native machine binaries built for a different architecture.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // CRITICAL: standalone traces production dependencies for minimal Docker size
  output: "standalone",
  compress: true,
  poweredByHeader: false,
  images: {
    formats: ["image/avif", "image/webp"],
    remotePatterns: [{ protocol: "https", hostname: "**" }],
  },
};

export default nextConfig;

# Step 1: Base Alpine Image
FROM node:20-alpine AS base
WORKDIR /app
RUN apk add --no-cache libc6-compat

# Step 2: Install Dependencies
FROM base AS deps
COPY package.json package-lock.json* ./
# If using Prisma, copy the schema before npm ci
COPY prisma ./prisma
RUN npm ci

# Step 3: Build Standalone Bundle
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production
RUN npx prisma generate
RUN npm run build

# Step 4: Ultra-Minimal Production Runner
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

# Security: Never run containers as root
RUN addgroup --system --gid 1001 nodejs &&     adduser --system --uid 1001 nextjs

# Copy standalone build and public static files
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

name: Build & Deploy via Coolify

on:
  push:
    branches: [main]

jobs:
  build-container:
    runs-on: ubuntu-latest # Free 16GB RAM runner
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

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

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Trigger Coolify Webhook
        run: |
          curl -X POST "${{ secrets.COOLIFY_WEBHOOK_URL }}"

Patch 1: Boost Node.js V8 Memory Allocation

In your Vercel Project Settings > Environment Variables, add:

This forces Node to delay garbage collection and grab up to 4GB of virtual space if available.

Patch 2: Switch SSG to Incremental Static Regeneration (ISR)

In dynamic [slug]/page.tsx routes, add this configuration at the top:

In generateStaticParams(), return only the top 10-20 popular slugs (e.g. .slice(0, 20)). The remaining pages will build on-demand without timing out.

Patch 3: Enable Cloudflare Node Compatibility Flags

In your wrangler.toml or Cloudflare Pages project settings, add:

This polyfills Node Buffer, crypto, and EventEmitter modules on Cloudflare Workers.

1. Prisma Engine Binary Missing in Alpine Linux

Alpine uses musl libc rather than glibc. Ensure your schema.prisma has binaryTargets = ['native', 'linux-musl-openssl-3.0.x'] so the correct query engine is generated.

2. Docker Daemon Disk Space Filling Up Over Time

Each deployment creates layer caches. Add a weekly cron job on your VPS to purge unused dangling images: 0 3 * * 0 docker system prune -af --volumes.

3. Cloudflare DNS Orange Cloud 524 Timeout on Webhooks

If Cloudflare proxies your VPS domain, requests taking longer than 100 seconds return HTTP 524. When calling Coolify deploy webhooks, ensure the webhook subdomain is set to Grey Cloud (DNS only).

4. SQLite Database File Locking During Concurrent Container Writes

If using SQLite, mounting the file over network storage causes locks. Use local SSD volume mounts (/data/db.sqlite) with WAL mode enabled (PRAGMA journal_mode=WAL).

5. Persistent File Uploads Directory (public/uploads)

Containers are ephemeral; files saved inside are lost on restart. In Coolify, map a persistent volume mount from /var/lib/coolify/uploads to /app/public/uploads.

6. Traefik Reverse Proxy Header Forwarding

Ensure your Next.js server trusts proxy headers (X-Forwarded-Proto: https, X-Forwarded-For) so auth cookies and redirects work seamlessly.

7. Next.js Image Optimization Cache Exhaustion

Sharp optimizes remote images in memory. Set images: { minimumCacheTTL: 2592000 } (30 days) in next.config.ts to avoid redundant re-optimizations.

8. Database Connection Pooling with PgBouncer

Serverless functions exhaust connection pools. On a VPS, run PgBouncer in transaction mode or use Prisma connection pool tuning (connection_limit=10).

9. Zero-Downtime Rolling Deploys with Healthchecks

Define a healthcheck in your Dockerfile (HEALTHCHECK --interval=5s --timeout=3s CMD wget -qO- http://localhost:3000/api/health || exit 1) so Coolify only switches traffic when the new container is healthy.

10. Automated Offsite Backups with S3 or Cloudflare R2

Coolify has built-in automated database backups. Configure a free Cloudflare R2 bucket and set backups to trigger every night at 02:00 UTC.