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
gofmton 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 --fix | frontend/src/ | Lints and auto-fixes TypeScript/TSX files |
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.
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 against proxima_test |
make test-e2e | Run E2E smoke tests against proxima_test (port 18080) |
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 |