From localhost to Production: Deploy Your React App on Self-Hosted Kubernetes
From localhost to Production: Deploy Your React App on Self-Hosted Kubernetes
You’ve got a Kubernetes cluster humming along. Certificates are green. Ingress is configured. And yet, every project you build still lives at localhost:5173 like it’s paying rent there. Time to evict it.
This guide walks through the actual deployment pipeline: from scaffolding a React app to pushing a container image to GitHub Container Registry (GHCR) and orchestrating it on your self-hosted cluster with TLS termination. No managed services. No cloud vendor lock-in. Just you, your cluster, and a working production URL.
Cloud providers offer convenience at the cost of control and recurring fees. A self-hosted cluster gives you full ownership of your infrastructure, predictable costs, and the satisfaction of knowing exactly where your bits live. The trade-off is operational responsibility—but if you're reading this, you've already accepted that bargain.
Init
What you need
Before diving in, ensure you have:
A working Kubernetes cluster (k3s, kubeadm, or similar)
kubectlconfigured and pointing to your clusterdockerinstalled locally for building imagesGitHub account
Node.jsandyarnfor local developmentA domain pointing to your cluster’s ingress controller
cert-managerconfigured with a ClusterIssuer (for TLS)
Apply
Create and Test Your React Project Locally
Spin up a fresh React project using Vite. The --template react flag gives you a minimal, modern setup without the bloat of create-react-app.
yarn create vite react --template react
When prompted, accept the defaults. Vite will scaffold the project, install dependencies, and drop you into a ready-to-run state.
To start project again after scaffolding
cd react
yarn dev
Then open http://localhost:5173 in your browser. You should see the default Vite + React welcome page. Congratulations—your project works. Locally. Like every other project you’ve abandoned in your ~/projects graveyard.
Prepare the Project for Docker
To ship this beyond your machine, you need a container. Create two files in your project root: a Dockerfile for the build process and a .dockerignore to keep the image lean.
This Dockerfile uses a multi-stage build. Stage one compiles your React app with Node. Stage two copies only the static output into an NGINX image. The result is a production image under 50MB instead of 1GB+ of node_modules debris.
Dockerfile
# Stage 1: Build
FROM node:22-alpine AS builder
WORKDIR /app
# Copy dependency files
COPY package.json yarn.lock ./
# Install dependencies
RUN yarn install --frozen-lockfile
# Copy source
COPY . .
# Build static files
RUN yarn build
# Stage 2: Runtime (NGINX)
FROM nginx:1.27-alpine
# Copy compiled React build to NGINX
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
.dockerignore
node_modules
build
dist
.git
.gitignore
*.log
.DS_Store
.env
.env.local
Build and Push to GitHub Container Registry
GHCR provides free container hosting tied to your GitHub account. Authenticate Docker with your Personal Access Token, build the image, and push it.
First, export your token:
bash
export GITHUB_TOKEN=ghp_your_token_here
fish
set -gx GITHUB_TOKEN ghp_your_token_here
Login to GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
# ↑ replace with your GitHub username
Expected output
WARNING! Your credentials are stored unencrypted in '/home/user/.docker/config.json'.
Configure a credential helper to remove this warning. See
https://docs.docker.com/go/credential-store/
Login Succeeded
Build the image with your GHCR path
docker build -t ghcr.io/YOUR_GITHUB_USERNAME/react:latest .
# ↑ replace with your GitHub username in lowercase
The build will pull base images, install dependencies, compile your app, and package it into the NGINX runtime. Output will show each layer being processed—grab coffee if your network is slow.
Push to the registry:
docker push ghcr.io/YOUR_GITHUB_USERNAME/react:latest
# ↑ replace with your GitHub username in lowercase
Once complete, your image lives at ghcr.io/YOUR_GITHUB_USERNAME/react:latest. You can verify it exists in your GitHub profile under Packages.
By default, GHCR packages are private. Either make the package public in GitHub's UI, or configure imagePullSecrets (covered next) to authenticate your cluster.
Real-world Application
Ah yes, the classic developer flex: “Check out this app I built!” followed by the crushing silence when someone asks for the URL and you mumble something about port 5173 and SSH tunnels. Your mom doesn’t want to install kubectl to see your todo app.
What follows is the unsexy middle: YAML files, registry authentication, ingress configuration. It’s not hard, but it’s not nothing. Let’s fix your localhost shame—and in the process, you’ll understand exactly why platforms like Vercel charge what they do (and why ZipOps exists as an alternative).
Step 1: Create the Namespace
Isolate your deployment in its own namespace. Clean separation, easy cleanup if things go sideways.
namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: test-react
And apply it as first resource
kubectl apply -f namespace.yaml