Local ZITADEL + Next.js Stack

Single entrypoint for the full stack:

• two clusters (vault and platform)
• Envoy Gateway + CloudNativePG + ZITADEL
• Argo CD (in-cluster, app GitOps)
• Terraform-provisioned ZITADEL project/OIDC app
• Next.js app deployed in Kubernetes

Environment model:

• use a single ENV value (local, dev, staging, prod, ...)
• each environment is configured in environments/<env>/
• local is the fast-iteration profile and deploys reference-web directly from this repo (no GitOps repo dependency)
• non-local environments deploy app workloads through Argo CD from a Git repository

Prerequisites

• kind
• kubectl
• helmfile
• terraform
• docker
• jq
• openssl

Bring everything up

cd /Users/martin.zokov/playground/mass-claw/platform-boilerplate
make ROOT="/Users/martin.zokov/playground/mass-claw/platform-boilerplate" ENV=local up

Other examples:

make ENV=dev gitops-up
make ENV=staging gitops-up
make ENV=prod gitops-up

This runs two stages:

• make clusters-up (cluster lifecycle)
• make apps-up (runtime/apps lifecycle)

If you still have a legacy single-cluster setup running, delete it first to free ports 80/443:

kind delete cluster --name kind

Access:

• App: http://app.localhost
• Dev App: Argo app deploys to dev namespace (not routed on host by default)
• ZITADEL: http://auth.localhost
• Mock API (JWT protected): http://api.localhost
• Headlamp (cluster UI): http://headlamp.localhost

Run and test starter app

1) Start platform dependencies

make up
make status

2) Log in to the starter app

Open http://app.localhost and log in via ZITADEL.

3) Call a JWT-protected backend through Envoy Gateway

The stack ships a mock backend protected by Envoy Gateway JWT validation:

# no token -> 401
curl -i -H 'Host: api.localhost' http://127.0.0.1/

# valid token -> 200
curl -i -H 'Host: api.localhost' -H "Authorization: Bearer <access-token>" http://127.0.0.1/

Troubleshooting

"account 'admin' does not have apiKey capability" – Argo CD needs accounts.admin: apiKey, login in argocd-cm. If Helm values don't apply, patch directly:

kubectl --context kind-platform -n argocd patch cm argocd-cm --type merge -p '{"data":{"accounts.admin":"apiKey, login"}}'
kubectl --context kind-platform -n argocd rollout restart deployment argocd-server

"connection refused" on login – Ensure port-forward is running, or use argocd login --port-forward. With server.insecure: true, add --plaintext to the login command.

Useful commands

make status
make ENV=dev doctor
make ENV=dev deploy
make ENV=dev destroy
make ENV=dev validate-env
make ENV=dev DOMAIN=example.com LE_EMAIL=you@example.com VAULT_KUBE_CONTEXT=<ctx> PLATFORM_KUBE_CONTEXT=<ctx> deploy
make clusters-up
make apps-up
make apps-up-local
make apps-down
make gitops-up
make gitops-up-local
make gitops-down
make clusters-down
make down

GitOps app delivery with Argo CD

Argo CD runs in the platform cluster (argocd namespace) and manages app deployments from this repository.

Before first make apps-up, set your repo URL in environments/<env>/argocd-bootstrap.values.yaml:

git:
  repoURL: https://github.com/<org>/<repo>.git

Current bootstrap manages one reference-web environment per cluster for non-local environments. The selected environment is set by ENV and loaded from environments/<env>/argocd-bootstrap.values.yaml.

For local bootstrap overrides, edit environments/local/argocd-bootstrap.values.yaml and run make gitops-up-local.

For a full local dual-run flow (Argo in-cluster app + host pnpm dev), see docs/local-dual-run.md.

Available overlay presets:

• runtime-gitops/apps/reference-web/dev/values.yaml
• runtime-gitops/apps/reference-web/prod/values.yaml

If you later run separate dev/prod clusters, use the same repo and set each cluster ENV plus matching environments/<env>/argocd-bootstrap.values.yaml. Promotion then becomes a PR from dev image tag to prod image tag.

For CI/CD deployment into non-local clusters, see docs/cicd-live-environments.md.

For the selected GitOps architecture (per-cluster Argo + bootstrap then pull-based reconcile), see docs/gitops-option1-3-monorepo.md.

For Oracle Kubernetes Engine setup steps, see docs/oke-live-setup.md.

For internet-facing OKE dev deployment with TLS and DNS, see docs/oke-dev-internet-deploy.md.

For the customer-operated MVP deployment flow, see docs/customer-deploy.md.

To run against non-kind clusters, set contexts and a platform secrets override file:

CLUSTER_MODE=external \
VAULT_KUBE_CONTEXT=<vault-context> \
PLATFORM_KUBE_CONTEXT=<platform-context> \
PLATFORM_SECRETS_VALUES_FILE=/path/to/platform-secrets-values.yaml \
make apps-up

JWT-protected mock API checks

# no token -> 401
curl -i -H 'Host: api.localhost' http://127.0.0.1/

# valid token -> 200
curl -i -H 'Host: api.localhost' -H "Authorization: Bearer <access-token>" http://127.0.0.1/

Add a backend service (GitOps)

To add a new backend behind Envoy Gateway:

• Deploy your Deployment + Service.
• Add an HTTPRoute that attaches to Gateway/platform-gateway.
• Add a SecurityPolicy that targets the HTTPRoute and enables JWT validation (same pattern as the mock API).
• Create an Argo CD Application for the folder that contains those manifests.

Repository structure

• runtime-vault/ Vault runtime and external NodePort exposure chart
• runtime-platform/ platform runtime (External Secrets, CNPG, ZITADEL, Envoy, app)
• runtime-gitops/ Argo CD values/bootstrap and environment overlays
• runtime-core/kind/ kind cluster configs for vault and platform
• runtime-core/platform-secrets/ External Secrets bindings for Vault-backed Kubernetes secrets
• reference-web/ reference web client template (Next.js app + Terraform OIDC provisioning)
• model-b/ isolated roadmap/spec scaffolding for future Auth-BFF profile

Model B roadmap

Planned Auth-BFF (broker) profile spec and layout:

• model-b/docs/spec.md
• model-b/docs/when-to-use.md
• model-b/docs/repo-layout.md