Deploy on Kubernetes

The Kubernetes setup is intentionally minimal: one YAML file, one helper script, and one CI workflow. The whole thing fits on one screen, reads top to bottom, and is easy to extend later.

k8s/
├── README.md
└── prod/
    ├── k8s-prod.yaml         Namespace + Deployment + Service + Ingress
    ├── create-secrets.sh     builds the `vibestrap-secrets` Secret from .env.prod
    └── .env.prod             your production env (gitignored — see .env.example)

What ships in the manifest

k8s/vibestrap.yaml defines four resources, in this order:

Namespace — vibestrap
Deployment — Next.js app, 1 replica, probes on /api/ping, sane resource requests/limits
Service — ClusterIP fronting the pods on port 80 → 3000
Ingress — nginx + cert-manager TLS, with www → apex redirect baked in

A single image is pulled from Harbor: harbor.funkro.com/vibestrap/vibestrap. There is no in-cluster migration Job — see Database migrations below.

What the CI does for you

.github/workflows/docker-build-push.yml runs on:

Every push to main
Every tag matching v*
Manual dispatch from the GitHub Actions UI

On each run it:

Builds the image

The runner stage of the Dockerfile becomes harbor.funkro.com/vibestrap/vibestrap:<version>, also re-tagged as :latest.

Pushes to Harbor

Authenticated with HARBOR_USERNAME + HARBOR_PASSWORD from GitHub Actions secrets.

Computes the version tag

Tag pushes use the git tag (e.g. v1.2.0). Branch pushes use main-<sha7>. Both forms are immutable, unlike :latest.

Auto-bumps the manifest

The workflow rewrites the image: line in k8s/vibestrap.yaml to point at the new version and commits back to main with [skip ci]. The manifest in git always reflects what is actually in the registry.

No kubeconfig lives in CI. The deploy itself is still your hands-on-keyboard step — by design.

GitHub Actions secrets

Add these once in Settings → Secrets and variables → Actions:

Secret	What goes in it
`HARBOR_USERNAME`	Your Harbor account username
`HARBOR_PASSWORD`	Harbor password, or a robot account token

First-time setup

Three things need to exist in the cluster before the first kubectl apply.

1. Harbor pull secret

So the cluster can pull from your private registry:

kubectl create namespace vibestrap
kubectl create secret docker-registry harbor-secret \
  --namespace vibestrap \
  --docker-server=harbor.funkro.com \
  --docker-username='<YOUR_HARBOR_USERNAME>' \
  --docker-password='<YOUR_HARBOR_PASSWORD>'

K8s pull secrets are namespace-scoped — harbor-secret in default or any other namespace cannot be used by a pod in vibestrap. Always pass --namespace vibestrap. The most common deploy failure is ImagePullBackOff because this secret was created in the wrong place.

If you’ve already created harbor-secret for another app in this cluster, copy it into the vibestrap namespace instead of retyping credentials:

kubectl get secret harbor-secret -n <other-ns> -o yaml \
  | sed '/namespace:/s/<other-ns>/vibestrap/; /resourceVersion:\|uid:\|creationTimestamp:/d' \
  | kubectl apply -f -

2. App secrets — only two values are required

The runtime image refuses to start without DATABASE_URL and BETTER_AUTH_SECRET. Every other env var is optional and no-ops gracefully when blank — you can deploy first, configure features later by re-running the script and kubectl rollout restart.

cp .env.example k8s/.env
# edit k8s/.env. ONLY two lines need real values:
#   DATABASE_URL=postgres://user:pass@host:5432/db
#   BETTER_AUTH_SECRET=<openssl rand -base64 32>
# Leave the rest blank until you actually want that feature.
./k8s/create-secrets.sh

The helper script strips comments, blank lines, and accidental quotes (kubectl treats quotes as part of the value, which breaks Better Auth and Stripe SDKs), then runs kubectl create secret generic ... --from-env-file for you. The Deployment pulls every variable in via envFrom: secretRef.

k8s/.env is gitignored. Don’t commit it. Re-run create-secrets.sh whenever you add or change a value.

3. ingress-nginx + cert-manager

The Ingress assumes ingressClassName: nginx and a letsencrypt-prod ClusterIssuer. If you don’t have them yet:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx --create-namespace

helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager --create-namespace \
  --set installCRDs=true

Then create a letsencrypt-prod ClusterIssuer following the cert-manager docs.

Database migrations

Migrations are not run by the cluster. The runtime image doesn’t include drizzle-kit, and there’s no Job to babysit. Instead, before each release that touches schema, run from your laptop:

DATABASE_URL='postgres://user:pass@prod-host:5432/db?sslmode=require' \
  pnpm db:migrate

Then kubectl apply the new image. With 1 replica there’s no race-condition window — schema moves only when you tell it to.

When prod DB is in a private VPC

If your laptop can’t reach the prod DB directly, spin up a one-off pod inside the cluster that has the right network access. The exact kubectl run command lives in k8s/README.md; the shape is:

kubectl run vibestrap-migrate --rm -it --restart=Never \
  --namespace vibestrap \
  --image=node:22-alpine \
  --env="DATABASE_URL=$DATABASE_URL" \
  -- sh -c "cd /tmp && git clone <repo> app && cd app && \
            corepack enable && pnpm install && pnpm db:migrate"

This is the heavy fallback — only reach for it when you genuinely can’t reach the DB from outside the cluster.

Deploy

Once the CI workflow has bumped the manifest, every deploy is:

git pull

# only if the release includes a schema change
DATABASE_URL='postgres://...' pnpm db:migrate

kubectl apply -f k8s/vibestrap.yaml

# watch the rollout
kubectl rollout status deployment/vibestrap -n vibestrap

If you only changed env vars (no new code), refresh the Secret and roll the Deployment:

./k8s/create-secrets.sh
kubectl rollout restart deployment/vibestrap -n vibestrap

When you outgrow this

The manifest is intentionally minimal — add these only when you actually need them. Each is small (10–30 lines) and orthogonal.

Add	When	Where
`HorizontalPodAutoscaler`	Traffic varies enough that fixed replicas wastes money or starves under load	New file under `k8s/`
`PodDisruptionBudget`	Running ≥3 replicas and you want zero-downtime node drains	New file
`NetworkPolicy`	Multi-tenant cluster, want to restrict egress to DB and outbound APIs	New file
`topologySpreadConstraints`	Multi-zone cluster, want zone-failure tolerance	Inline in the Deployment spec
Multiple environments	When you actually run more than the `vibestrap` namespace	`k8s/staging/` parallel directory

Troubleshooting

Symptom	Likely cause	Check
`ImagePullBackOff`	Harbor credentials wrong, or `harbor-secret` missing in `vibestrap` namespace	`kubectl get secret harbor-secret -n vibestrap`
Pod `CrashLoopBackOff` on first start	Missing required env (`DATABASE_URL`, `BETTER_AUTH_SECRET`, …)	`kubectl logs <pod> -n vibestrap` — Zod prints the missing key
Pod boots but DB queries throw “column does not exist”	Forgot to run `pnpm db:migrate` before applying the new image	Run the migration from your laptop, then restart the Deployment
TLS cert pending forever	DNS not pointing at the ingress LB, or ClusterIssuer missing	`kubectl describe certificate vibestrap-tls -n vibestrap`
Stripe webhook 400 “invalid signature”	`STRIPE_WEBHOOK_SECRET` mismatched	Re-copy from Stripe, refresh secret, restart Deployment

Getting started

Authentication

Payments

AI primitives

Growth

Content & i18n

Operations

Deployment

Reference

Deploy on Kubernetes

What ships in the manifest

What the CI does for you

GitHub Actions secrets

First-time setup

1. Harbor pull secret

2. App secrets — only two values are required

3. ingress-nginx + cert-manager

Database migrations

When prod DB is in a private VPC

Deploy

When you outgrow this

Troubleshooting

Official docs

​What ships in the manifest

​What the CI does for you

​GitHub Actions secrets

​First-time setup

​1. Harbor pull secret

​2. App secrets — only two values are required

​3. ingress-nginx + cert-manager

​Database migrations

​When prod DB is in a private VPC

​Deploy

​When you outgrow this

​Troubleshooting

​Official docs

What ships in the manifest

What the CI does for you

GitHub Actions secrets

First-time setup

1. Harbor pull secret

2. App secrets — only two values are required

3. ingress-nginx + cert-manager

Database migrations

When prod DB is in a private VPC

Deploy

When you outgrow this

Troubleshooting

Official docs