Development Setup

This guide covers IDE configuration, pre-commit hooks, environment variables, Docker services, and the full set of Makefile commands for day-to-day development.

IDE Recommendations

VS Code

Recommended extensions:

• Go (golang.go) -- Go language support, debugging, and test runner
• ESLint (dbaeumer.vscode-eslint) -- JavaScript/TypeScript linting
• Prettier (esbenp.prettier-vscode) -- Code formatting
• Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss) -- Tailwind class autocomplete
• EditorConfig (editorconfig.editorconfig) -- Consistent editor settings

GoLand / WebStorm

JetBrains IDEs have built-in support for Go, TypeScript, and ESLint. Enable the following:

• Go modules integration (enabled by default)
• ESLint -- Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint > Automatic Configuration
• Prettier -- Settings > Languages & Frameworks > JavaScript > Prettier > On save
• File Watchers for gofmt on save

Pre-commit Hooks

The project uses pre-commit to run checks before every commit. Install the hooks after cloning:

pip install pre-commit
pre-commit install

The hooks defined in .pre-commit-config.yaml include:

Hook	Scope	What it does
gofmt	agent/, backend/	Formats Go source files
golangci-lint	agent/, backend/	Runs the full Go linter suite
eslint	frontend/src/	Lints TypeScript/TSX. Reports only — it does not pass --fix, unlike the prettier hook below.
prettier --write	frontend/src/	Formats TypeScript, TSX, and CSS files
swagger-validate	backend/docs/swagger.*	Validates swagger spec is well-formed Swagger 2.0
swagger-freshness	backend/internal/**.go	Verifies the swagger spec is up to date with annotations
check-yaml	All files	Validates YAML syntax
check-json	All files	Validates JSON syntax
check-merge-conflict	All files	Detects leftover merge conflict markers
detect-private-key	All files	Prevents accidental commit of private keys
changelog-check	commit-msg	Ensures CHANGELOG.md is updated for the commit

Environment Variables

Copy .env.example to .env and adjust values as needed:

cp .env.example .env

Key Variables

Variable	Default	Description
PROXIMA_DB_URL	postgres://proxima:proxima_dev@localhost:5432/proxima?sslmode=disable	PostgreSQL connection string
PROXIMA_NATS_URL	nats://localhost:4222	NATS server address
PROXIMA_SERVER_PORT	8080	Backend HTTP port
PROXIMA_INSTALL_TOKEN	—	One-time install token for agent enrollment (generate via API)
PROXIMA_LOG_LEVEL	debug	Log verbosity (debug, info, warn, error)
PROXIMA_CORS_ORIGINS	http://localhost:5173	Allowed CORS origins
PROXIMA_CLIENT_SLUG	internal	Client identifier for the agent
PROXIMA_ENVIRONMENT_SLUG	development	Environment identifier for the agent
VITE_API_BASE_URL	http://localhost:8080/api/v1	Frontend API base URL

OpenTelemetry (Optional)

Tracing is disabled by default. To enable it, uncomment these variables in .env:

PROXIMA_OTEL_ENABLED=true
PROXIMA_OTEL_EXPORTER_ENDPOINT=localhost:4317
PROXIMA_OTEL_SERVICE_NAME=proxima-backend

Docker Services

make docker-up starts the following containers via Docker Compose:

Service	Container Name	Image	Ports
PostgreSQL 18	proxima-postgres	pgvector/pgvector:pg18	5432
NATS + JetStream	proxima-nats	nats:2.10-alpine	4222 (client), 8222 (HTTP monitor)
Vault	proxima-vault	hashicorp/vault:1.18	8200 (API/UI, localhost only)
Valkey	proxima-valkey	valkey/valkey:8-alpine	6379
Tempo	proxima-tempo	grafana/tempo:2.7.2	3200 (HTTP API), 4317 (OTLP gRPC), 4318 (OTLP HTTP)
VictoriaMetrics (vmstorage)	proxima-vmstorage	victoriametrics/vmstorage:v1.136.0-cluster	8482 (API), 8400 (insert), 8401 (select)
VictoriaMetrics (vminsert)	proxima-vminsert	victoriametrics/vminsert:v1.136.0-cluster	8480
VictoriaMetrics (vmselect)	proxima-vmselect	victoriametrics/vmselect:v1.136.0-cluster	8481

Data is persisted in Docker volumes (proxima-pg-data, proxima-nats-data, proxima-vm-data, proxima-vault-data), so it survives docker compose down. To fully reset data, remove the volumes:

docker compose down -v

First-Time Vault & NATS JWT Setup

After starting Docker services for the first time, initialize Vault and generate NATS JWT credentials:

# 1. Initialize Vault (operator init + unseal + PKI + KV + AppRole)
#    Saves unseal key and root token to infra/vault/.vault-keys
make vault-init

# 2. Generate NATS operator/account JWTs and backend credentials
make nats-jwt-init

# 3. Issue NATS TLS server certificate from Vault PKI
make nats-cert-issue

# 4. Add Vault credentials to your .env file
#    (vault-init prints VAULT_ROLE_ID and VAULT_SECRET_ID)

On subsequent runs, Vault auto-unseals using the saved key. You only need to re-run these steps if you reset the Vault volume.

Running without Vault

make nats-jwt-init is not Vault-only. With --keystore=disk (or PROXIMA_KEYSTORE=disk in the environment) it persists the operator and account nkey seeds on the keys volume and constructs no Vault client, so a rig without Vault can still stand up NATS JWT mode:

PROXIMA_KEYS_DIR=/absolute/path/to/keys \
  sh -c 'cd backend && go run ./cmd/nats-jwt-init --keystore=disk'

Give PROXIMA_KEYS_DIR an absolute path: this tool runs from backend/ and the server runs from the repo root, so the relative default ./keys would put the seeds in backend/keys/ where the server never looks.

Steps 1 and 4 above then do not apply, and Step 3 needs the NATS server certificate from somewhere other than Vault PKI. See Disk Keystore for creating the keys volume.

Useful URLs

URL	Description
http://localhost:8080	Backend API
http://localhost:8080/healthz	Liveness probe
http://localhost:8080/readyz	Readiness probe
http://localhost:5173	Frontend (Vite dev server)
http://localhost:8222	NATS HTTP monitoring
http://localhost:8200/ui	Vault UI
http://localhost:3004	Grafana (Tempo tracing datasource)

Makefile Commands

The Makefile in the project root provides all standard development commands. Run make help to see them all.

Command	Description
make help	Show all available commands
make build	Build agent, backend, and frontend
make build-agent	Build the agent binary
make build-backend	Build the backend binary
make build-frontend	Build frontend static files
make test	Run all tests (agent + backend + frontend)
make test-race	Run Go tests with the race detector
make test-integration	Run integration tests. Each run clones proxima_test_template into a throwaway proxima_test_run_<pid>_<rand> database and drops it afterwards, so runs never collide.
make test-e2e	Build locally, then run the E2E suite (BATS and Playwright) on the remote E2E server over SSH. Use make test-e2e-ci for a purely local BATS run.
make test-db-setup	Create proxima_test database, run migrations, seed
make test-db-reset	Drop and recreate proxima_test from scratch
make test-coverage	Run tests with coverage reports
make lint	Run all linters (Go + frontend)
make lint-go	Run golangci-lint on agent and backend
make lint-frontend	Run ESLint and Prettier on frontend
make run-backend	Start the backend server
make run-agent	Start the agent
make run-frontend	Start the frontend dev server
make docker-up	Start PostgreSQL, NATS, VictoriaMetrics, Tempo, and Grafana containers
make docker-down	Stop all Docker containers
make docker-logs	Tail Docker service logs
make migrate-up	Apply all pending database migrations
make migrate-down	Roll back the last migration
make migrate-create	Create a new migration (usage: make migrate-create name=add_users)
make migrate-status	Show current migration version
make seed	Seed development data (clients, environments)
make vault-init	Initialize Vault (operator init, unseal, PKI, AppRole)
make nats-jwt-init	Generate NATS operator/account JWTs and credentials
make nats-cert-issue	Issue NATS TLS server certificate from Vault PKI
make swagger	Generate Swagger/OpenAPI docs
make swagger-validate	Validate swagger spec is well-formed
make swagger-check	Verify swagger spec is up to date with annotations
make clean	Remove build artifacts