spb/spbgit Public MIT

1<!--2  ─────────────────────────────────────────────3   SPB Git — Personal Git Platform4  ─────────────────────────────────────────────5   Author  : Simon-Pierre Boucher6   Contact : contact@spboucher.ai7   File    : README.md8   Purpose : Project overview, quick start, operations guide9   License : MIT © Simon-Pierre Boucher10  ─────────────────────────────────────────────11-->12<div align="center">1314# SPB Git1516**The personal git platform of Simon-Pierre Boucher**1718[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](https://nodejs.org)19[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)20[![runtime](https://img.shields.io/badge/runtime-Fastify%205-black)](https://fastify.dev)21[![deploy](https://img.shields.io/badge/host-m3u96a-4f8cff)](https://git.spboucher.ai)2223Self-hosted software forge · every repo public & clonable · owner-only writes2425`https://git.spboucher.ai`2627</div>2829---3031## What it is3233SPB Git is a complete, self-hosted GitHub-equivalent built for one person:3435- **Git hosting** — Smart HTTP v2 (streamed `upload-pack`/`receive-pack`), anonymous clone/fetch, PAT-authenticated push, post-receive hooks, zip/tar.gz snapshots.36- **Showcase web UI** — SSR (Nunjucks), dark/light themes, pinned repos, activity feed, contribution heatmap, GitHub-grade README rendering (badges, mermaid, task lists, relative images), shiki-highlighted file browsing with line anchors, commits, diffs, blame, branches, tags, global search, OG cards, Atom feed, sitemap.37- **`spbgit` CLI** — the terminal command center: `init`, `token`, `list`, `create --push`, `clone --all`, `status`, `commit`, `push`, `pull`, `sync`, `open`, `info`, `rm`, `doctor`, `release`.38- **Releases** — GitHub-style binary assets (dmg, pkg, zip…) attached to tags, streamed to disk with sha256 sidecars, public downloads at `/releases/<repo>/<tag>/<file>`:39  ```bash40  git tag v1.0.0 && git push --tags41  spbgit release upload myapp v1.0.0 MyApp.dmg   # → https://git.spboucher.ai/releases/myapp/v1.0.0/MyApp.dmg42  spbgit release list myapp43  ```44- **JSON API** — public reads, token-gated writes at `/api/v1/*`.4546**Filesystem is the database.** Bare repos under the git root are the source of truth; `meta.json` holds descriptions/topics/pins; everything expensive is cached per `<repo>@<sha>` and busted on push.4748## Quick start (development)4950```bash51npm install                 # also fetches self-hosted fonts52cp .env.example .env        # point the paths at ./dev/* for local work53npm run dev                 # http://127.0.0.1:742054```5556Mint a first token, then wire up the CLI:5758```bash59node --input-type=module -e "60import { loadConfig, ensureDirs } from './src/config.mjs';61import { TokenStore } from './src/auth/token.mjs';62const c = loadConfig(); ensureDirs(c);63console.log((await new TokenStore(c.dataDir).create('bootstrap')).token);64"65npm link                    # exposes `spbgit`66spbgit init                 # paste server URL + token67spbgit create hello --push  # first repo, live immediately68```6970## Deployment (node m3u96a)7172```bash73# on m3u96a, from the app directory74bash deploy/setup-m3u96a.sh75```7677The script is idempotent: checks node ≥ 20 / git / ngrok / pm2, creates the78data prefix (`/srv` on Linux, `~/srv` on macOS), installs production deps,79writes `.env`, prints the **bootstrap PAT once**, and starts both pm2 apps80(`spbgit-server`, `spbgit-tunnel`). Run `pm2 startup` once so everything81survives a reboot. DNS: CNAME `git.spboucher.ai` to the ngrok edge target82(see `deploy/ngrok.yml`). Nightly backups: cron `deploy/backup.sh` (keeps 14).8384A systemd unit is provided as the documented alternative: `deploy/spbgit.service`.8586## Scripts8788| Command | Purpose |89|---|---|90| `npm start` / `npm run dev` | run the server (dev = watch + template reload) |91| `npm test` | vitest — unit + full clone/push round-trip e2e |92| `npm run lint` | eslint |93| `npm run check:headers` | fail if any file lacks the author header |94| `npm run inject:headers` | add missing headers in bulk |95| `npm run fetch:fonts` | (re)download self-hosted Inter / JetBrains Mono |9697## Security model9899- All repositories are **public read-only**; there is no private flag anywhere.100- Writes require a PAT (`spbgit_<id>_<secret>`), stored argon2id-hashed, revocable, with last-used tracking.101- Repo names match `^[a-z0-9][a-z0-9._-]{0,63}$`; tree paths are traversal-checked twice (validation + prefix check).102- Rendered Markdown is sanitized with a strict allowlist (badges, `<details>`, `<kbd>`, align HTML survive; scripts, iframes, event handlers never do).103- `/raw` serves with `nosniff` + sandbox CSP, and repo HTML is served as `text/plain`.104- `/internal/*` hook routes accept loopback connections only.105106## License107108MIT © [Simon-Pierre Boucher](mailto:contact@spboucher.ai)109