Quick Start
Get Proxima Console running locally in under 10 minutes. This guide assumes you have all prerequisites installed.
1. Clone the Repository
git clone https://gitlab.prxm.uz/proxima/console.git
cd console
2. Configure Environment Variables
Copy the example environment file and review the defaults:
cp .env.example .env
The defaults in .env.example work out of the box for local development. 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 API port |
PROXIMA_NATS_CREDS_FILE | infra/nats/creds/proxima-backend.creds | Path to backend NATS credentials file (generated by make nats-jwt-init) |
3. Start Infrastructure Services
Start PostgreSQL, NATS (with JetStream), VictoriaMetrics Cluster, Valkey, Tempo, and Grafana:
make docker-up
This runs COMPOSE_PROFILES=dev docker compose up -d, which starts roughly a dozen containers (PostgreSQL, NATS, Valkey, Vault, Tempo, VictoriaLogs, the three VictoriaMetrics cluster components, Grafana, and more). Give them a few seconds to come up, then check their status:
COMPOSE_PROFILES=dev docker compose ps
Each service should show a running (and, where a healthcheck is defined, healthy) status before you continue.
4. Apply Database Migrations
Create the database schema:
make migrate-up
This applies all pending migrations from backend/migrations/ using golang-migrate.
5. Seed Development Data
Populate the database with sample clients and environments:
make seed
This runs scripts/seed-data.sh, which inserts test clients, environments, and related reference data.
6. Start the Backend
make run-backend
The backend API server starts on port 8080. Leave this terminal running.
7. Start the Agent
The agent needs a backend URL and a one-time install token to enroll — neither is in .env.example by default.
For the agent to connect to NATS after enrolling, Vault and NATS JWT credentials
must be bootstrapped first (make vault-init, make nats-jwt-init,
make nats-cert-issue). See Development Setup → First-Time Vault & NATS JWT
Setup. The enrollment step below
still works without it, but the agent's NATS connection will not.
First, generate an install token. The easiest way is the in-app Installation Wizard: open the frontend (started in step 8) at http://localhost:5173/hosts/add, pick Linux, choose a client/environment, and click Generate Install Command — the token is shown once. Alternatively, call the API directly once you have a JWT:
curl -X POST http://localhost:8080/api/v1/clients/{slug}/install-tokens \
-H "Authorization: Bearer <your-jwt>" \
-H "Content-Type: application/json" \
-d '{"description": "dev agent", "expires_in": 86400, "max_uses": 1}'
Then set the backend URL and token in your .env (or export them) before starting the agent:
export PROXIMA_BACKEND_URL=http://localhost:8080
export PROXIMA_INSTALL_TOKEN=<generated-token>
Open a new terminal and start the agent:
make run-agent
On first run the agent enrolls with the backend, connects to NATS, and begins collecting host inventory data.
8. Start the Frontend
Open another terminal:
make run-frontend
The frontend dev server starts on port 5173 with hot module replacement enabled.
9. Verify the Stack
Check that the backend is running and ready:
# Liveness check — is the process running?
curl http://localhost:8080/healthz
# Expected: {"status":"ok"}
# Readiness check — are all dependencies (DB, NATS) connected?
curl http://localhost:8080/readyz
# Expected: {"status":"ok"}
Open the frontend in your browser at http://localhost:5173.
Service Ports
| Service | URL | Description |
|---|---|---|
| Backend API | http://localhost:8080 | REST API |
| Frontend | http://localhost:5173 | React dev server |
| NATS Monitoring | http://localhost:8222 | NATS HTTP monitor |
| Grafana (Tempo) | http://localhost:3004 | Distributed tracing (via Tempo datasource) |
| PostgreSQL | localhost:5432 | Database (connect via psql) |
| NATS | localhost:4222 | Message broker |
| Valkey | localhost:6379 | Auth cache (sessions, rate limits, MFA) |
| Grafana | http://localhost:3004 | Metrics dashboards |
| VictoriaMetrics Insert | localhost:8480 | Metrics ingestion |
| VictoriaMetrics Select | localhost:8481 | Metrics queries |
Stopping Everything
To stop the application processes, press Ctrl+C in each terminal.
To stop the Docker infrastructure services:
make docker-down
Next Steps
See the Development Setup guide for IDE configuration, pre-commit hooks, and the full list of Makefile commands.