Development Setup

Prerequisites

Tool	Version	Installation
Go	1.22+	go.dev
Node.js	20+	nodejs.org
Docker	24+	docker.com
Docker Compose	v2	Included with Docker Desktop
golang-migrate	latest	go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
golangci-lint	v2	golangci-lint.run

First-Time Setup

# 1. Clone the repository
git clone <repo-url> && cd invoice

# 2. Start PostgreSQL
make docker-up

# 3. Run migrations
make migrate-up

# 4. Configure environment
cp backend/.env.example backend/.env
# Edit .env with your ClickHouse DSN and JWT secret

# 5. Install frontend dependencies
cd frontend && npm install && cd ..

# 6. Start backend
make run-backend   # Port 8081

# 7. Start frontend (new terminal)
make run-frontend  # Port 5173

Environment Variables

Create backend/.env with:

INVOICE_DB_URL=postgres://invoice:invoice@localhost:5433/invoice?sslmode=disable
INVOICE_CLICKHOUSE_DSN=https://default:[email protected]:443/default
INVOICE_JWT_SECRET=change-me-in-production
INVOICE_PDF_CONVERTER_URL=https://convert.prxm.uz
INVOICE_SERVER_PORT=8081
INVOICE_CORS_ORIGINS=http://localhost:5173

See Environment Variables for the complete list.

Makefile Commands

Build & Run

Command	Description
make build	Build Go binary to bin/invoice-server
make run-backend	Start Go server (port 8081)
make run-frontend	Start Vite dev server (port 5173)

Testing

Command	Description
make test	Run all unit tests
make test-race	Tests with Go race detector
make test-coverage	Generate HTML coverage report
make test-integration	Integration tests (needs Docker)
make test-e2e	End-to-end smoke tests
make test-db-setup	Create and migrate test database

Linting & Formatting

Command	Description
make lint	Run golangci-lint + ESLint
make lint-backend	Go linting only
make lint-frontend	TypeScript/React linting only
make format	Prettier format frontend code

Database

Command	Description
make docker-up	Start PostgreSQL container
make docker-down	Stop PostgreSQL container
make migrate-up	Apply all pending migrations
make migrate-down	Rollback last migration
make migrate-create NAME=xxx	Create new migration pair
make migrate-status	Show current migration version
make seed	Note: seed data included in migrations

Documentation

Command	Description
make docs-dev	Start Docusaurus dev server
make docs-build	Build documentation site

Test Database

For isolated testing:

make test-db-setup

This creates an invoice_test database, runs all migrations, and seeds data. Tests use TEST_DB_URL for the connection string.

Docker Services

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    container_name: invoice-postgres
    ports:
      - "5433:5432"
    environment:
      POSTGRES_USER: invoice
      POSTGRES_PASSWORD: invoice
      POSTGRES_DB: invoice

Note: Port 5433 is used to avoid conflicts with other PostgreSQL instances (proxima-backend uses 5432).