roommates/
├─ docker-compose.yml db, rustfs, backup, mailpit and app services
├─ deploy/ PostgreSQL, RustFS, backup, Mailpit and app images
└─ app/ Go module (run go/task commands from here)
├─ cmd/server/ entry point (main.go) and routes
├─ internal/ application code
│ ├─ config/ env, routes, cookie/header keys
│ ├─ db/ migrations, queries/, sqlc output (dbqueries/)
│ ├─ handlers/ HTTP layer
│ ├─ services/ business logic used by handlers
│ ├─ storage/ file contents in an S3 API (RustFS)
│ ├─ mailer/ SMTP email (Mailpit in development)
│ ├─ push/ web push notifications
│ ├─ events/ images/ middleware/ models/ validators/ sessions/ logger/ utils/
│ └─ locales/ translations (en, et) and generated keys
├─ web/
│ ├─ components/ shared templ components (shadcn-templ ui)
│ ├─ pages/ full pages (home, chat, expenses, files, notes, shopping, …)
│ ├─ renderer/ gin <-> templ renderer
│ └─ assets/ css, favicon, pwa, public/ (embedded static files)
├─ tools/ dev and build time programs, see tools/README.md
├─ scripts/ dev, format and lint scripts
└─ certificates/ local mkcert TLS cert/key (not committed)After Setup. Run from app/ unless noted.
- From the repo root:
cp .env.example .env, then replace theREPLACE_WITH_*and`openssl …`values - Create the TLS certificate: app/certificates/README.md
task vendordownloads htmx and the fonts (not committed,task devdoes not fetch them), see app/web/assets/README.md- Mailpit gives an inbox at http://127.0.0.1:8025 (
task devstarts it). To send emails to the log instead, comment outSMTP_HOSTin.env task devstarts db + rustfs + mailpit and serves the app with hot reload on https://localhost:8090. The database is migrated on starttask seedadds example users and a household
Whole stack in Docker instead: docker compose up --build from the repo root, app on https://127.0.0.1:8000. That also runs the backup service (db dump + files into ./backups), see deploy/backup/README.md for config and restore.
Install golang
Install Docker with compose (PostgreSQL, RustFS and Mailpit run in it)
Install mkcert for the local certificate
Install binaries with go
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest- sqlc
- generate go code to interact with database
go install github.com/go-task/task/v3/cmd/task@latest- taskfile
- similar to makefile
go install github.com/go-delve/delve/cmd/dlv@latest- delve
task devruns the server under it (debugger on 127.0.0.1:2345)
go install honnef.co/go/tools/cmd/staticcheck@latest- staticcheck, used by
scripts/lint.sh
- staticcheck, used by
templ and shadcn-templ need no install: they are pinned as tool in go.mod and run with go tool templ / go tool shadcn-templ
Install tailwindcss at the version pinned as TAILWIND_VERSION in Taskfile.yml so that it is usable with tailwindcss command (task tailwind and task build refuse other versions)
used in Taskfile.yml required by https://shadcn-templ.com/docs/installation#existing-project
Install golangci-lint
From app/:
task buildbuilds for production →bin/appsh scripts/lint.shruns staticcheck + golangci-lintsh scripts/format.shrunstempl fmt+gofmtgo test ./...skips DB tests unlessTEST_POSTGRES_DBnames a throwaway database (the migration test drops all tables), never the dev database
Code generation (regenerate after editing the source, never edit the output):
sqlc generate:internal/db/queries/*.sql→internal/db/dbqueries/go tool templ generate:*.templ→*_templ.gogo generate ./tools/...:internal/locales/yaml → locale keys