hanna/fabrica

docs: add README

bf1c5f1 · hanna committed on 2026-07-26

Project overview, feature list, quick start (Docker + Nix), configuration,
CLI table, architecture, and development notes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

README.md +141 −0

@@ @@ -0,0 +1,141 @@ @@
 # fabrica
 *fabrica* (Latin: **forge**) is a self-hosted git server — a single Rust binary that serves
 your repositories over **HTTPS** (read) and **SSH** (read + write) behind a fast, themeable,
 htmx-driven web UI. Private by default, no sign-up required.
 It aims to be a **complete forge minus CI**, feature-comparable to Forgejo/Gitea: code
 browsing, nested groups, three-level visibility, issues and pull requests with server-side
 merge machinery, and a full account-settings area — all from one binary, one config file, and
 one data directory.
 ## Features
 - **Code browsing** — files, history, diffs, branches, and tags, with syntax highlighting
   everywhere code appears (including inside diffs and rendered markdown) and per-commit
   signature verification (SSH and GPG).
 - **Nested groups** — organize repositories under arbitrarily (up to 5 levels) nested,
   user-owned groups. Renames and moves are metadata-only.
 - **Three-level visibility** — public / internal / private, with a per-instance default and
   explicit collaborators (read / write / admin). Private repos 404 rather than 403, never
   leaking their existence.
 - **Issues & pull requests** — toggleable per repository, with GitHub-style **scoped labels**
   (`kind: value`), assignees, comments, locking, and open/closed state. PRs include branch
   comparison, diff review, and server-side **merge / squash / rebase**.
 - **Accounts** — optional web self-registration (toggleable, with optional hCaptcha/reCAPTCHA)
   alongside admin invites; account settings for username, email, password, SSH/GPG keys, API
   tokens, and profile.
 - **Admin dashboard** — instance stats, user/repo/group management, sign-up invites, and
   config overrides.
 - **Themeable, no build step** — server-rendered [`maud`](https://maud.lambda.xyz/) templates
   enhanced with vendored htmx; every interactive element works without JavaScript. Themes are
   single CSS files of `--fb-*` custom properties; drop one in and `SIGHUP` to load it.
 - **JSON API** under `/api/v1`, and a CLI that operates directly on the store (no IPC with a
   running server).
 **Out of scope:** orgs, forks, stars, followers, notifications, wikis, releases-as-a-feature,
 git-LFS, webhooks, mirroring, federation. **CI is deferred** — the seams exist (inert behind
 `ui.show_runs = false`) but the runner is not built yet.
 ## Requirements
 The `git` binary (**≥ 2.41**) must be on `PATH` at runtime — fabrica shells out to it for pack
 transport (`upload-pack` / `receive-pack`) and maintenance, while using libgit2 in-process for
 browsing. Every deployment path below guarantees it; verify with `fabrica doctor`.
 ## Quick start
 ### Docker / Compose
 ```sh
 docker compose up
 ```
 Builds the image and starts fabrica on `:8080` (HTTP) and `:2222` (SSH) with named volumes for
 data and repos. SQLite is the default database; add `--profile postgres` and point
 `FABRICA__DATABASE__URL` at it to use Postgres.
 ### From source (Nix)
 The toolchain (Rust nightly via fenix) is pinned in the flake:
 ```sh
 nix develop                 # enter the dev shell
 just check                  # fmt + check + clippy + test (the quality gate)
 cargo run -- serve          # serve with the built-in defaults
 ```
 `serve` runs in the foreground (correct for systemd/Docker) and applies pending migrations on
 startup. Create the first administrator:
 ```sh
 cargo run -- user add alice alice@example.com --admin
 ```
 Then open <http://localhost:8080>.
 ## Configuration
 Copy [`fabrica.example.toml`](fabrica.example.toml), edit it, and point the binary at it with
 `--config <path>` (or place it at `/etc/fabrica/fabrica.toml` or under `$XDG_CONFIG_HOME/fabrica/`).
 Every key can be overridden by an environment variable `FABRICA__<SECTION>__<KEY>` (double
 underscores nest), and any `*_file` key reads its value from a file — for agenix, systemd-creds,
 or Docker secrets. Unknown keys are a hard error.
 ```sh
 fabrica config check        # validate
 fabrica config show         # print the merged config, secrets redacted
 ```
 On first run fabrica generates its HS256 secret and SSH host key. See
 [`docs/configuration.md`](docs/configuration.md) and [`docs/deployment.md`](docs/deployment.md)
 for details — including the reverse-proxy rule that pack routes **must not be buffered**.
 ## CLI
 Every subcommand touches the store and filesystem directly; there is no running-server IPC.
 | Command | Purpose |
 |---|---|
 | `fabrica serve` | Run the HTTP + SSH server (foreground) |
 | `fabrica user` | Manage accounts (add, passwd, admin, verify, disable, del) |
 | `fabrica repo` | Manage repositories (add, rename, visibility, collaborator, archive, path…) |
 | `fabrica group` | Manage groups |
 | `fabrica key` / `token` | Manage SSH/GPG keys and API tokens |
 | `fabrica config` | Validate / show the effective configuration |
 | `fabrica migrate` | Apply database migrations |
 | `fabrica doctor` | Check the runtime environment (git on PATH, etc.) |
 ## Architecture
 A single root binary (`src/main.rs`) dispatches into library crates under `crates/`, with a
 strictly one-way dependency direction:
 ```
 model  ←  store / git / auth  ←  web / api / ssh / cli
 ```
 - `model` (domain types, no I/O) · `config` (figment TOML+env) · `store` (sqlx, SQLite **and**
   Postgres over one portable schema) · `git` (libgit2 reads + `git` subprocess pack transport)
 - `highlight` (tree-sitter) · `auth` (argon2id, sessions, JWT) · `mail` (lettre)
 - `ssh` (russh) · `web` (axum + maud + htmx) · `api` (`/api/v1` JSON) · `cli` (clap)
 Repositories are stored on disk by ULID (`{repo_dir}/{id[0..2]}/{id}.git`); the database is the
 only name→path authority, so renames and group moves are metadata-only. See
 [`spec.md`](spec.md) for the full design contract and [`docs/decisions.md`](docs/decisions.md)
 for the running log of design decisions and deviations.
 ## Development
 ```sh
 just check          # cargo fmt --check + check + clippy -D warnings + test
 nix flake check     # the superset: clippy, fmt, test, deny, doc
 ```
 The workspace forbids `unsafe_code` and denies `unwrap`/`panic`/`todo` outside tests. `cargo
 test` alone suffices with no external services (Postgres tests are feature-gated). Commits
 follow Conventional Commits, scoped by crate/area.
 ## License
 [MPL-2.0](LICENSE).