Operate / Run Veefore

Deployment

Containers, Kubernetes, Helm and Terraform — plus the network topology that makes the plane split worth having.

The repository ships deployment definitions under infrastructure/, validated by npm run infra:validate as a stage of npm run verify.

#Build

bashCopy
npm run build                 # backend and console
npm run build:backend
npm run build:console

bashCopy
docker build -f infrastructure/docker/Dockerfile -t veefore:1.0.0 .

One image, three entry points. The processes share almost all their code, and a single image means one thing to scan, sign and promote.

bashCopy
node dist/control-plane/server.js
node dist/gateway/server.js
node dist/control-plane/worker.js

#Network topology

This is the part that makes the plane split worth having.

textCopy
                    Internet / your VPC
                            │
          ┌─────────────────┴─────────────────┐
          │                                   │
    ingress: console              ingress: gateway
    + control plane                /gateway/v1/* only
    /v1/* only                            │
          │                               │
   people, CLI, CI                     agents
          │                               │
          └───────────────┬───────────────┘
                          │
                   PostgreSQL (private)

The database is private to both planes. Nothing outside the cluster or VPC reaches it.

#Kubernetes

bashCopy
kubectl apply -f infrastructure/kubernetes/base.yaml
kubectl apply -f infrastructure/kubernetes/control-plane.yaml
kubectl apply -f infrastructure/kubernetes/gateway.yaml

The probes are the important part of those manifests:

yamlCopy
livenessProbe:
  httpGet: { path: /health/live, port: http }
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /health/ready, port: http }
  initialDelaySeconds: 5
  periodSeconds: 5

/health/ready genuinely checks the database, so a pod with a broken connection leaves rotation instead of serving errors.

Both planes are stateless — session state and the job queue are in the database — so horizontal scaling needs no coordination. Scale them independently: the gateway sees high-volume, latency-sensitive agent traffic; the control plane sees low-volume, bursty human and CI traffic. 3:1 is a reasonable starting ratio.

Run at least one worker replica. Job claiming is tenant-safe and guarded against overlapping poll ticks, so several can run concurrently. With none, webhooks never deliver and usage never rolls up, and nothing visibly breaks.

#Secrets

bashCopy
kubectl create secret generic veefore-keys \
  --from-literal=VEEFORE_DATA_ENCRYPTION_KEY=… \
  --from-literal=VEEFORE_SIGNING_PRIVATE_KEY=… \
  --from-literal=VEEFORE_SIGNING_KEY_ID=… \
  --from-literal=VEEFORE_SESSION_SECRET=… \
  --from-literal=VEEFORE_AUDIT_CHAIN_SECRET=…

Better: an external secrets operator pulling from your secret manager, so rotation does not mean editing a manifest.

#Rollout order

1. Migrations, as a job that completes before anything restarts. Forward-only and safe against the previous version.
2. Control plane, rolling.
3. Gateway, rolling.
4. Worker. Any time; in-flight jobs are reclaimed.
5. Console static assets.

Gateway after the control plane, so the control plane is already on the new schema when the gateway starts depending on it.

#TLS

Terminate at your ingress. Both planes speak HTTP behind it.

veefore doctor reports a control plane or gateway reachable over plaintext HTTP on a non-loopback host as a finding. Egress has the same rule enforced rather than reported: a tool endpoint must be HTTPS unless its host is loopback.

#Terraform

infrastructure/terraform/ provisions the database, the networking and the secret references. It does not provision the application — that is Helm or raw manifests, so you can move the application forward without touching infrastructure state.

bashCopy
cd infrastructure/terraform
terraform init
terraform plan

#Validate before you ship

bashCopy
npm run infra:validate

Checks that the container, Kubernetes, Helm and Terraform definitions are well formed. Part of npm run verify.

#Scaling signals

That last one is a real trap: without Redis, each instance keeps its own rate limit and nonce state, so your effective limit is multiplied by your instance count and nonce replay protection is weaker than you think.

#Related