Faith & Code | Reflections by Errong

Health Checks and Scaling Strategies for Next.js in Kubernetes This is Part 6 and the final post of the series: Self-Hosting Next.js in Kubernetes (Without Vercel) . At this point, your Next.js standalone app: Builds cleanly Runs in a minimal Docker image Deploys correctly on Kubernetes / OpenShift Serves static assets properly Uses runtime configuration and secrets Now let’s make it resilient and scalable . Why Health Checks Matter Kubernetes relies on health checks to: Know when a pod is ready to receive traffic Restart unhealthy containers Safely roll out new versions Without proper probes, traffic can be sent to a pod that isn’t ready yet. Readiness Probe A readiness probe tells Kubernetes: “This pod can accept traffic.” For most Next.js apps, the root path works well: readinessProbe: httpGet: path: / port: 3000 initialDelaySeconds: 10 periodSeconds: 5 If your app depends on downstream services (APIs, d...

Managing Environment Variables and Secrets for Next.js in Kubernetes This is Part 5 of the series: Self-Hosting Next.js in Kubernetes (Without Vercel) . By now, your Next.js standalone app is: Built correctly Running in a minimal Docker image Deployed on OpenShift or Kubernetes The next challenge is managing configuration and secrets without rebuilding your image every time. Build-Time vs Runtime Environment Variables This distinction is critical in Next.js. Build-Time Variables Resolved during npm run build Inlined into the JavaScript bundle Cannot be changed without rebuilding Examples: NEXT_PUBLIC_API_URL NEXT_PUBLIC_FEATURE_FLAG Runtime Variables Read when server.js starts Can be changed via Kubernetes Ideal for secrets and environment-specific config DATABASE_URL REDIS_HOST INTERNAL_API_TOKEN What Works Best for Standalone Deployments For self-hosted Next.js: Use build-time vars sparingly Prefer runt...

Fixing 404 Errors for _next/static in Next.js Standalone Deployments This is Part 4 of the series: Self-Hosting Next.js in Kubernetes (Without Vercel) . If your Next.js app works locally but returns 404 errors for /_next/static/* after deploying to Kubernetes or OpenShift, this post is for you. This is the most common issue with Next.js standalone deployments. The Symptom After deployment, you may see: Blank pages Missing CSS or JavaScript 404 errors in browser dev tools for /_next/static/* Yet the server itself is running fine. Why This Happens In standalone mode, Next.js: Bundles the server into server.js Includes only required Node.js dependencies Does NOT automatically include static assets That means: .next/standalone exists .next/static exists But they are not wired together On Vercel, this is handled for you. In Kubernetes, you must do it yourself . How Standalone Mode Resolves Paths When running i...

Deploying a Next.js Standalone App on OpenShift This is Part 3 of the series: Self-Hosting Next.js in Kubernetes (Without Vercel) . In the previous posts, we: Built a Next.js app in standalone mode Created a minimal, production-ready Docker image Now we’ll deploy that image into OpenShift using standard Kubernetes resources: Deployment , Service , and Route . Assumptions This guide assumes: Your image is already built and pushed to an internal registry The container listens on PORT=3000 The app runs using Next.js standalone server.js 1️⃣ Deployment The Deployment runs the Next.js standalone server as a stateless container. apiVersion: apps/v1 kind: Deployment metadata: name: example-nextjs spec: replicas: 2 selector: matchLabels: app: example-nextjs template: metadata: labels: app: example-nextjs spec: containers: - name: web image: image-registry.openshift-image-registry.svc...

Building a Minimal Docker Image for Next.js Standalone Apps This is Part 2 of the series: Self-Hosting Next.js in Kubernetes (Without Vercel) . In Part 1 , we covered how to run a Next.js app in standalone mode. Now let’s improve the deployment by building a clean, minimal Docker image that works well in Kubernetes and OpenShift. Why Multi-Stage Docker Builds Matter A common mistake is shipping your entire source tree and development dependencies into production. A multi-stage Docker build allows you to: Keep build tools out of production Reduce image size significantly Improve security Speed up CI and deployments For Next.js standalone apps, this pattern works extremely well. Stage 1: Builder Image The builder stage installs dependencies and runs the normal Next.js build. Nothing special happens here. FROM node:22-alpine AS builder WORKDIR /build COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build At this poin...

Most Next.js tutorials assume you deploy on Vercel . That works great — until you are in an enterprise environment where: You must deploy into OpenShift or a Kubernetes cluster You need a custom Node.js runtime image You want full control over networking, certificates, and scaling In this post, we’ll walk through how to deploy a Next.js app in standalone mode , using a normal build process and a custom Docker image — no Vercel involved. Why Standalone Mode ? Next.js standalone mode bundles: The compiled server ( server.js ) Only the required Node.js dependencies A minimal runtime footprint This makes it ideal for containerized environments like OpenShift and Kubernetes. 1️⃣ Build the App Normally There is nothing special here. You still install dependencies and run a standard Next.js build: npm ci npm run build Your next.config.js must enable standalone output: module.exports = { output: 'standalone', }; 2️⃣ Underst...