Skip to main content

Upgrade Guide

This page documents breaking changes and upgrade procedures between Proxima Console versions.

How upgrades happen now (production is GitOps on Kubernetes)

The application tier runs in the proxima-production Kubernetes cluster and is upgraded via GitOps, not by SSH-ing to a box and running docker compose / systemctl. A production upgrade is:

  1. Merge the release to main.
  2. CI builds + pushes registry.prxm.uz/proxima/console/<svc>:<git-sha>.
  3. Run the deploy:k8s-gitops job (manual gate) — it bumps the image tags in the argocd-infra repo.
  4. ArgoCD syncs: the console-migrate PreSync Job runs migrate up against psql01, then Argo Rollouts does the backend blue-green promotion.

So below, wherever older steps say "run make migrate-up" / "systemctl restart" / "docker compose up", in production those are handled for you by the PreSync migration Job and the Rollout. Those literal commands now apply to local dev (and the version-specific sections that pre-date the Kubernetes migration are kept as historical record). See Backend Deployment for the full flow.

v0.5.x to v0.6.0​

Breaking config — a naive deploy will not start

v0.6.0 ships the RBAC and authentication security remediations. The backend now fails fast at startup on a weak PROXIMA_JWT_SECRET (< 32 chars) or out-of-range JWT TTLs, fail-closes MFA when PROXIMA_MFA_ENCRYPTION_KEY is unset/invalid (MFA users can't log in), and rejects secretless webhooks. There are 28 new migrations and a coordinated backend-first / agents-second NATS rollout.

Read the full deploy runbook before upgrading: docs/releases/v0.6.0.md — it has the breaking-config checklist at the top, the migration list, the agent rollout order, and post-deploy verification.

Quick pre-flight​

  1. PROXIMA_JWT_SECRET ≥ 32 chars; PROXIMA_JWT_ACCESS_TTL 60–3600s; PROXIMA_JWT_REFRESH_TTL 300–2592000s (all fail startup if out of range).
  2. PROXIMA_MFA_ENCRYPTION_KEY set (64 hex chars) or MFA users are locked out.
  3. PROXIMA_TRUSTED_PROXY_COUNT matches the nginx/edge hop count.
  4. Run migrations (make migrate-up → version 80) before/with the new backend. In production, migrations run automatically as the console-migrate ArgoCD PreSync Job before the backend sync — make migrate-up is the local-dev equivalent.
  5. Deploy backend first, then agents (un-updated agents fall back to cached config — non-fatal); flip PROXIMA_REQUIRE_RENEWAL_NONCE=true after the fleet renews. In production, the backend ships via deploy:k8s-gitops → ArgoCD → Argo Rollouts; the agent fleet is rolled out separately.

v0.1.x to v0.2.0​

Breaking Changes

v0.2.0 replaces TimescaleDB with VictoriaMetrics for all time-series storage. This is a significant infrastructure change.

What Changed​

ComponentBefore (v0.1.x)After (v0.2.0)
Metrics storageTimescaleDB (PostgreSQL extension)VictoriaMetrics Cluster
PostgreSQL roleRelational + time-seriesRelational only
PostgreSQL version16+ with TimescaleDB18+ (no extensions required)
Metrics write pathSQL INSERT to metrics tableHTTP POST to vminsert
Metrics query pathSQL with time_bucketMetricsQL via vmselect
Docker ComposePostgreSQL onlyPostgreSQL + vmstorage + vminsert + vmselect

Pre-Upgrade Checklist​

  1. Back up your PostgreSQL database — especially the metrics table if you want to preserve historical data.
  2. Note your current Docker volumes — the upgrade adds new volumes for VictoriaMetrics.
  3. Review new environment variables — VM_INSERT_URL and VM_SELECT_URL are required for the backend.

Upgrade Steps​

1. Stop all services​

docker compose down
systemctl stop proxima-backend

2. Update Docker Compose​

Pull the latest docker-compose.yml which includes VictoriaMetrics services:

git pull origin main
docker compose up -d

This starts PostgreSQL 18, NATS, vmstorage, vminsert, and vmselect.

3. Run database migrations​

make migrate-up

This runs two new migrations:

  • 000008 — Adds vm_account_id column to the clients table (auto-incrementing sequence for VictoriaMetrics tenant isolation).
  • 000009 — Removes the TimescaleDB extension, drops the metrics hypertable, and removes related continuous aggregates.
caution

Migration 000009 drops the metrics table. All historical time-series data stored in TimescaleDB will be lost. If you need to preserve this data, export it before upgrading.

4. Configure backend environment​

Add VictoriaMetrics URLs to your backend configuration:

export VM_INSERT_URL=http://localhost:8480
export VM_SELECT_URL=http://localhost:8481

Or add to your .env file / systemd unit.

5. Restart backend​

systemctl start proxima-backend
# or
make run-backend

The backend will begin writing new metrics to VictoriaMetrics immediately. Historical data from before the migration is not carried over.

6. Update agents​

Deploy the v0.2.0 agent binary to managed hosts. The agent message format is unchanged — no configuration changes are needed on the agent side.

Rollback​

To roll back to v0.1.x:

  1. Stop the backend
  2. Run make migrate-down (reverses migration 000009, reinstalls TimescaleDB)
  3. Revert to the v0.1.x backend binary
  4. Remove VictoriaMetrics services from Docker Compose
note

Rolling back does not restore metrics data that was written to VictoriaMetrics during the v0.2.0 period.

v0.1.0 to v0.1.1​

No breaking changes. This is a maintenance release.

Changes​

  • Go version bump: 1.24.0 to 1.24.13 (fixes 14+ stdlib CVEs)
  • golangci-lint v1.64 to v2.9
  • Swagger/OpenAPI documentation added at /swagger
  • Documentation site deployed at docs-console.prxm.uz
  • Deployment model: binary + static files to Docker containers

Upgrade Steps​

  1. Pull the latest code and rebuild
  2. No database migrations required
  3. Deploy new Docker images

General Upgrade Procedure​

For any version upgrade, first read the Changelog for the target version and ensure psql01 has a recent pgBackRest backup before migrations run.

Production (Kubernetes / GitOps)​

  1. Merge the release to main; CI builds + pushes registry.prxm.uz/proxima/console/<svc>:<git-sha>.
  2. Run the deploy:k8s-gitops job (manual gate) to bump the image tags in argocd-infra.
  3. ArgoCD runs the console-migrate PreSync Job (migrations against psql01) and then syncs the backend; Argo Rollouts performs the blue-green promotion once /readyz passes.
  4. Update agents separately after the backend is live (agents are backwards-compatible with newer backends).
  5. Verify — kubectl -n console-system argo rollouts get rollout console-backend, check https://api-console.prxm.uz/readyz, and review pod logs (kubectl -n console-system logs deploy/console-backend). See Backend Deployment.

Local development​

  1. git pull and rebuild images.
  2. make migrate-up before starting the new backend.
  3. Restart with make run-backend (or docker compose up -d for the infra services).
  4. Verify — check the /readyz endpoint and review logs for errors.