getting-started.md

Getting started

Three ways in, from lightest to most complete. All three end on the same app at http://localhost:8080 (or labs.localhost for the third).

SQLite dev — no Docker

make setup       # answers a few questions, writes .env
make front       # build the Vue app once (embedded by the Go server)
make dev         # DB auto-created and migrated

make setup asks the handful of questions that matter — product name, tenancy mode, what you sell — and leaves the other ~45 variables at their documented defaults. .env.example stays the exhaustive reference.

For frontend work with hot reload, run both:

make dev                 # Go API on :8080
cd web && npm run dev    # Vite on :5173, proxies /api to :8080

Docker with PostgreSQL

docker compose up

Builds the image, starts PostgreSQL and Mailpit, migrates, serves. One command, ready to use.

The labs — everything, locally

docker compose -f deploy/labs/docker-compose.yml up -d --build

The full experience: the app plus single sign-on, S3 uploads, a Stripe API double and a mail inbox, with nothing to configure. It deserves its own page: the labs.

Requirements

• Go ≥ 1.26, Node ≥ 22 (development); Docker (optional)
• Code generation and linting: sqlc, goose, golangci-lint (in ~/go/bin — keep it on PATH)

First commands worth knowing

Command	What
make test	Go suite (unit + integration, real database)
make test-front	vitest
make e2e	Playwright against the real production binary
make lint	golangci-lint + eslint
make sqlc	regenerate typed queries after editing .sql files
make seed	idempotent demo data (refuses production)
make build	the production binary, frontend embedded