Skip to main content

Quick Start

Get Proxima Invoice running locally in under 5 minutes.

Prerequisites​

  • Go 1.22+
  • Node.js 20+
  • Docker and Docker Compose
  • golang-migrate CLI (go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest)
  • Access to ClickHouse at clickhouse-api.prxm.uz (for real data) or mock data

1. Start Docker Services​

make docker-up

This starts PostgreSQL on port 5433.

2. Run Migrations​

make migrate-up

Applies all migrations (11 files) including seed data for:

  • Company settings (ProximaOps LLC)
  • Bank details (Капиталбанк)
  • Default rate rules
  • Project classifications
  • Employee exclusions

3. Configure Environment​

Create .env in the backend/ directory:

# Required
INVOICE_DB_URL=postgres://invoice:invoice@localhost:5433/invoice?sslmode=disable
INVOICE_CLICKHOUSE_DSN=https://default:[email protected]:443/default
INVOICE_JWT_SECRET=your-secret-key-here

# PDF Generation
INVOICE_PDF_CONVERTER_URL=https://convert.prxm.uz

# Optional
INVOICE_SERVER_PORT=8081
INVOICE_CORS_ORIGINS=http://localhost:5173

See Environment Variables for all options.

4. Start the Backend​

make run-backend

The Go server starts on port 8081. Verify with:

curl http://localhost:8081/healthz

Expected: {"status":"ok","version":"dev",...}

5. Start the Frontend​

make run-frontend

The Vite dev server starts on port 5173. Open http://localhost:5173 in your browser.

6. Test the API​

# Login
TOKEN=$(curl -s -X POST http://localhost:8081/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.token')

# List clients
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8081/api/v1/clients

# Prefill an invoice
curl -X POST http://localhost:8081/api/v1/invoices/prefill \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"application_key":"APP-001"}'

Useful Commands​

make test          # Run all unit tests
make lint          # Run linters (Go + TypeScript)
make test-race     # Tests with race detector
make docker-down   # Stop Docker services

See the full command reference in the Makefile.