Deployment

Vezta deploys frontend and backend as Docker containers on self-hosted VMs with a defined branch promotion policy.

Branch Policy

Promotion path is dev → staging → main (each subproject — vezta-be, vezta-fe, vezta-docs — is its own git repository with its own workflows):

• dev -- integration. PRs merge here.
• staging -- release candidate. PRs from dev (or release/*, hotfix/*) merge here.
• main -- production. PRs from staging (or hotfix/*) only.

main requires 2 approvals + passing CI + Security Gates. staging requires 1 approval. Branch protections are enforced by the governance.yml workflow in each subproject repo.

Frontend (Docker on VMs)

The frontend deploys as a Docker container (ghcr.io/morcalabs/vezta-fe) on the same VMs as the backend.

Key env vars per environment:

# Production
NEXT_PUBLIC_API_URL=https://backend.vezta.io/api/v1
NEXT_PUBLIC_WS_URL=wss://backend.vezta.io

# Staging
NEXT_PUBLIC_API_URL=https://staging.vezta.io/api/v1
NEXT_PUBLIC_WS_URL=wss://staging.vezta.io

Production deploys (frontend)

frontend-deploy-production.yml takes a pinned image_ref as input (a ghcr.io/...:sha-... tag) and deploys that promoted image — there is no rebuild. Staging auto-deploys on push to the staging branch (with an optional image_ref input to skip the build). Rollback = re-run the workflow with a previous known-good image_ref.

Backend (Docker on self-hosted VMs)

The backend runs in 9 application containers per VM (1 API + 8 specialized workers) with self-hosted GitHub Actions runners.

Production VM

Staging VM

Worker Topology

Each VM runs 9 application containers (1 API + 8 workers) sharing the same ghcr.io/<owner>/vezta-be-api image:

Rollback: scale specialized workers to 0 and run a single fallback container with WORKER_DOMAIN=all. Same image works in both modes.

Promoted-image production deploy

Backend production deploys use a promoted-image model:

1. Push to staging triggers build.yml + deploy-staging.yml -- builds and tags ghcr.io/<owner>/vezta-be-api:sha-<sha12>
2. Production deploy workflow (deploy.yml) takes that image_ref as input -- no rebuild
3. Rollback via scripts/rollback-to-image.sh <env> <image>

CI/CD Flow

Both production and staging CI auto-run prisma migrate deploy -- never run migrations manually on the VM.

Post-deploy health check

Verifies:

• /api/v1/health (port 4001/4002 via Nginx)
• In-container liveness probes for each worker (ports 3002 / 3003 / 3004 / 3005 / 3006 / 3007 / 3008 / 3009)

Server .env

Located at the app path on each VM (e.g. /root/apps/vezta-be/.env on staging, ~/vezta/.env on production). Always back up before edits:

ssh root@<staging-vm> 'cd /root/apps/vezta-be && cp .env .env.bak.$(date +%s)'

After .env changes, recreate containers (a docker compose restart is not enough — env is loaded at create time):

ssh root@<staging-vm> 'cd /root/apps/vezta-be && docker compose up -d'

Nginx-Layer Concerns

Nginx (not NestJS) owns several concerns in production:

• CORS -- map $http_origin $cors_origin whitelist for vezta.io, dev.vezta.io, admin.vezta.io, localhost:3000. NestJS CORS headers are stripped via proxy_hide_header; Nginx adds its own with add_header ... always. OPTIONS preflight returns 204 directly from Nginx. Modifying enableCors() in main.ts has no effect in production.
• Rate limits -- api_general zone (30r/s, burst 50), api_auth zone (5r/s, burst 10) on /api/v1/auth/, 30 conn/IP, 10s body/header timeouts, 2MB body max
• SSL -- Auto-renewing via Certbot/Let's Encrypt
• Backups -- *.cors-backup files preserve previous configs

The Polymarket CLOB proxy runs on the dedicated vezta-proxy VM (Tinyproxy on port 8888), routing CLOB API calls from the production and staging VMs past geo-restrictions. Its address is supplied to the backend via environment variable, never hardcoded.

CI Runner and Proxy VMs

CI and the CLOB geo-bypass proxy run on two separate VMs (previously a single combined host):

• vezta-runner — hosts the self-hosted GitHub Actions runners. Jobs target these runner labels:

• vezta-proxy — runs Tinyproxy on port 8888, routing Polymarket CLOB API calls from the production and staging VMs past geo-restrictions.

Manual deploy (hotfix only)

scp src/some-file.ts agent@<production-vm>:~/vezta/src/some-file.ts
ssh agent@<production-vm> 'cd ~/vezta && docker compose down && docker compose build --no-cache api && docker compose up -d'

This bypasses the promoted-image model — only use it when CI/CD is broken and the situation is urgent. Always reconcile by re-running CI as soon as possible.

Key Conventions

• Never prisma migrate resolve --applied without running the migration. If a migration conflicts with manual DB changes, make the SQL idempotent (IF NOT EXISTS).
• Never run manual ALTER TABLE on production via psql. Schema changes go through Prisma migrations.
• Always dedup existing rows before adding unique constraints -- staging and production may have different data.