Deployment Guide
nextgin supports two primary production topologies using the exact same Go backend and Next.js App Router codebase.
1. All-in-One Self-Host (Render, Fly.io, Railway, VPS)
In selfhost mode, Go is the single public HTTP front door:
- Static assets (
/_next/static/*,/public/*) and prerendered HTML are served directly by Go. /api/*and/_nextgin/cron/*are handled in-process by Gonet/http.- Dynamic SSR, RSC, and Server Actions are proxied to Next.js standalone workers over Unix domain sockets with
WriteTimeout: 0so Suspense streaming never cuts off.
Sizing for Render 512 MB (Free / Starter)
A stripped pure-Go binary (CGO_ENABLED=0 -ldflags="-s -w") is ~8 MB and idles at ~10–15 MB RAM. Setting WORKERS=1 keeps total container memory around 100–140 MB — well inside a 512 MB instance.
FROM golang:1.24-alpine AS go-builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server .
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production WORKERS=1 TRUST_PROXY=1 PORT=8080
COPY --from=go-builder /app/server ./server
COPY .nextgin ./.nextgin
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://127.0.0.1:8080/_nextgin/health || exit 1
EXPOSE 8080
CMD ["./server"]
Health Checks & Zero-Downtime Rolling Deploys
Point your platform's health check at GET /_nextgin/health. On SIGTERM, Go stops accepting new connections, cancels cron contexts (r.Context()), drains active HTTP requests, and shuts down Next.js workers cleanly.
2. Split Mode: Vercel (or Cloudflare Pages) + Go Container
Keep your Next.js frontend on Vercel (or Cloudflare Pages) while your Go API, webhooks, and unlimited crons run on Render, Fly.io, Cloud Run, or Railway.
nextgin build \
--web-target vercel \
--backend-target container \
--backend-url https://api.example.com
Why Direct Browser → Go API Mode?
By default in split mode, browser requests go directly to https://api.example.com instead of proxying through Vercel rewrites:
- Zero Vercel API compute charges and no 10s–60s serverless timeout on long jobs.
- Parent-domain cookies: configure
SetSessionCookiewithDomain: ".example.com"andCORSwith explicithttps://example.comorigin. - No
api/directory at project root: keepweb/andbackend/separate so Vercel never mistakes Go files for legacy serverless functions.
Note on Cloudflare Workers / WASM
We intentionally do not compile the Go backend to Cloudflare Workers WASM. Native Go containers give you persistent PostgreSQL/SQLite connection pools, Unix sockets, full stdlib networking, and reliable in-process cron goroutines without WASM isolate limits. You can still host the Next.js frontend on Cloudflare Pages and point NEXT_PUBLIC_NEXTGIN_API_URL at your Go container.