Guides

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 Go net/http.
  • Dynamic SSR, RSC, and Server Actions are proxied to Next.js standalone workers over Unix domain sockets with WriteTimeout: 0 so 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 SetSessionCookie with Domain: ".example.com" and CORS with explicit https://example.com origin.
  • No api/ directory at project root: keep web/ and backend/ 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.