SPB Git
The personal git platform of Simon-Pierre Boucher
Author: Simon-Pierre Boucher
Self-hosted software forge · every repo public & clonable · owner-only writes
https://git.spboucher.ai
What it is
SPB Git is a complete, self-hosted GitHub-equivalent built for one person:
- Git hosting — Smart HTTP v2 (streamed
upload-pack/receive-pack), anonymous clone/fetch, PAT-authenticated push, post-receive hooks, zip/tar.gz snapshots. - Showcase web UI 3.0 "Monograph" — the editorial language of www.spboucher.ai (paper, ink, one indigo; Fraunces · Inter · IBM Plex Mono; see
docs/DESIGN.md), mobile-first, three themes (Light · Dark · Midnight), SSR (Nunjucks) with a small vanilla-JS layer: ruled figures, selected repos, a typographic repository index, searchable catalog, activity feed, contribution calendar with documented metrics (/about/metrics), GitHub-grade README rendering (badges, mermaid, task lists, relative images), lazy file tree, shiki-highlighted blobs with line anchors, commits, unified/split diffs, blame, branches, releases, per-repo insights, opt-in Research Mode, ⌘K search over repos/files/commits/branches, OG cards, Atom feed, sitemap. SeeCHANGELOG.mdanddocs/. - Live metric badges —
/badge/<repo>/<metric>.svg(commits, last commit, 26-week activity chart, language, size, branches, tags, license, clones; site totals under/badge/_site/), withstyle,labelandcoloroptions; each repository lists its Markdown under Insights. Reference:/about/api#badges. spbgitCLI — the terminal command center:init,token,list,create --push,clone --all,status,commit,push,pull,sync,open,info,rm,doctor,release.- Releases — GitHub-style binary assets (dmg, pkg, zip…) attached to tags, streamed to disk with sha256 sidecars, public downloads at
/releases/<repo>/<tag>/<file>:bashgit tag v1.0.0 && git push --tags spbgit release upload myapp v1.0.0 MyApp.dmg # → https://git.spboucher.ai/releases/myapp/v1.0.0/MyApp.dmg spbgit release list myapp - JSON API — public reads, token-gated writes at
/api/v1/*;/api/v1/search,/api/v1/repos/:name/tree. - AI (opt-in) — grounded repository Q&A and commit summaries with verified citations, provider-agnostic (
SPBGIT_AI_PROVIDER=anthropic|openai-compatible), disabled by default.
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.
Quick start (development)
npm install # fonts are tracked in git; postinstall only verifies them
cp .env.example .env # point the paths at ./dev/* for local work
npm run dev # http://127.0.0.1:7420Mint a first token, then wire up the CLI:
node --input-type=module -e "
import { loadConfig, ensureDirs } from './src/config.mjs';
import { TokenStore } from './src/auth/token.mjs';
const c = loadConfig(); ensureDirs(c);
console.log((await new TokenStore(c.dataDir).create('bootstrap')).token);
"
npm link # exposes `spbgit`
spbgit init # paste server URL + token
spbgit create hello --push # first repo, live immediatelyDeployment (M1M32, MacLustr gateway)
Production is the clone at M1M32:~/srv/spbgit/app under PM2 (mld manifest). Procedure, verification and rollback: docs/DEPLOY.md. The historical bootstrap below targets a fresh machine:
bash deploy/setup-m3u96a.shThe script is idempotent: checks node ≥ 20 / git / ngrok / pm2, creates the
data prefix (/srv on Linux, ~/srv on macOS), installs production deps,
writes .env, prints the bootstrap PAT once, and starts both pm2 apps
(spbgit-server, spbgit-tunnel). Run pm2 startup once so everything
survives a reboot. DNS: CNAME git.spboucher.ai to the ngrok edge target
(see deploy/ngrok.yml). Nightly backups: cron deploy/backup.sh (keeps 14).
A systemd unit is provided as the documented alternative: deploy/spbgit.service.
Scripts
| Command | Purpose |
|---|---|
npm start / npm run dev |
run the server (dev = watch + template reload) |
npm test |
vitest — unit + full clone/push round-trip e2e |
npm run lint |
eslint |
npm run check:headers |
fail if any file lacks the author header |
npm run inject:headers |
add missing headers in bulk |
npm run fetch:fonts |
(re)download self-hosted Inter / JetBrains Mono / Bricolage |
python3 -I scripts/qa/screens.py URL OUT |
responsive QA: overflow + touch targets + screenshots (Playwright for Python) |
python3 -I scripts/qa/axe.py URL |
WCAG 2.x A/AA audit with axe-core |
Security model
- All repositories are public read-only; there is no private flag anywhere.
- Writes require a PAT (
spbgit_<id>_<secret>), stored argon2id-hashed, revocable, with last-used tracking. - Repo names match
^[a-z0-9][a-z0-9._-]{0,63}$; tree paths are traversal-checked twice (validation + prefix check). - Rendered Markdown is sanitized with a strict allowlist (badges,
<details>,<kbd>, align HTML survive; scripts, iframes, event handlers never do). /rawserves withnosniff+ sandbox CSP, and repo HTML is served astext/plain./internal/*hook routes accept loopback connections only.
Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
License
MIT © Simon-Pierre Boucher