ForgeBucket — Developer Guide

Sovereign, federated Git collaboration platform.
Backend: Go 1.21+ · Frontend: React 18 + TypeScript + Vite · DB: PostgreSQL + XORM

Quick Start

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

2.1 KiB Raw Blame History