58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# ForgeBucket — Developer Guide
|
|
|
|
Sovereign, federated Git collaboration platform.
|
|
Backend: Go 1.21+ · Frontend: React 18 + TypeScript + Vite · DB: PostgreSQL + XORM
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cp .env.example .env # fill in SESSION_SECRET and CSRF_SECRET
|
|
make docker-up # start PostgreSQL
|
|
make migrate # run DB migrations
|
|
make dev # Go on :8080 + Vite on :5173
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
cmd/forgebucket/ binary entry point
|
|
internal/
|
|
api/ HTTP layer (Chi router, middleware, handlers)
|
|
domain/git/ sanitized git binary wrapper — no shell interpolation
|
|
domain/federation/ ActivityPub / ForgeFed implementation
|
|
domain/ci/ Forgejo Actions gRPC client
|
|
models/ XORM structs + migrations
|
|
config/ ENV-driven config, fails fast on missing secrets
|
|
web/ //go:embed target for built React SPA
|
|
frontend/ React 18 + TypeScript + Vite + Tailwind
|
|
```
|
|
|
|
## Key Rules
|
|
|
|
- **Git commands**: always `exec.Command("git", args...)` with discrete args — never build shell strings from user input
|
|
- **Secrets**: never hardcode; all secrets come from environment variables
|
|
- **CSRF**: all POST/PUT/DELETE routes require `X-CSRF-Token` header matching the session cookie
|
|
- **Auth chain**: `Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler`
|
|
- **8px grid**: all UI spacing must use multiples of 4px (xs) or 8px (sm) from `ui/tokens.ts`
|
|
- **Touch targets**: minimum 44px for all interactive elements
|
|
|
|
## Common Commands
|
|
|
|
| Command | What it does |
|
|
|---------|-------------|
|
|
| `make dev` | Start both servers concurrently |
|
|
| `make build` | Build frontend then embed into Go binary |
|
|
| `make migrate` | Sync XORM schemas to PostgreSQL |
|
|
| `make test` | Run Go tests + Vitest |
|
|
| `make lint` | go vet + ESLint |
|
|
| `make docker-up` | Start PostgreSQL via Docker Compose |
|
|
|
|
## Environment Variables
|
|
|
|
See `.env.example` for all required variables.
|
|
`SESSION_SECRET` ≥ 32 chars · `CSRF_SECRET` = exactly 32 chars.
|
|
|
|
## Module Path
|
|
|
|
`github.com/forgeo/forgebucket`
|