# aeolun/gothab

> Gothab test repository

- **Default branch:** `main`
- **Stars:** 1 · **Open issues:** 1 · **Open pull requests:** 1
- **Clone:** `https://gothab.home.serial-experiments.com/aeolun/gothab.git`

## README.md

# Gothab

A GitHub alternative for developers who are uneasy about where GitHub is
heading but don't want to run their own forge. Rust backend, SolidJS frontend,
PostgreSQL database.

## What's in the box

Everything you'd expect from a forge, plus a few things you wouldn't:

- **Git over HTTP and SSH** — push, fetch, clone, LFS, partial-clone-friendly
- **Issues, pull requests, code review** — threaded diff comments with
  multi-line selection, inline suggestions that apply in one click, comment
  survival across rebases, merge-conflict resolution in the browser
- **CI/CD** — GitHub Actions-compatible workflows, auto-scaling runners
  (Hetzner today, more providers on the way), per-job re-run with attempt
  history, live log streaming with collapsible `::group::` sections, and
  SSH-into-failing-build for debugging
- **Code search** — tantivy + tree-sitter, global and per-repo, symbol-aware,
  incremental on every push
- **Pages** — static site hosting with on-demand TLS and custom domains
- **Wiki** — a directory of markdown in your repo, pre-rendered, navigable
- **Packages** — mirroring live; native registry (npm, PyPI, Cargo, OCI…) on
  the roadmap
- **Federation** — mirrors from GitHub today; ForgeFed or git-over-email to be
  decided

See [`TODO.md`](TODO.md) for the full picture of what's shipped (`[x]`), in
progress (`[~]`), and planned (`[ ]`).

## Architecture at a glance

```
Browser → Caddy (static assets)
            ↓ (everything else)
       Bun SSR server (SolidJS renderToStringAsync)
            ↓ (API calls during SSR)
       Rust backend (gothab-server :3000)
            ↔ PostgreSQL
            ↔ Redis Streams (background tasks)
            ↔ Blobstore (content-addressed, local disk or R2 cold tier)
```

Frontend is SolidJS rendered server-side via Bun for SEO and link previews.
The Rust backend handles every API call, every git operation (HTTP and SSH),
and every background job. Caddy serves static assets directly via kernel
sendfile.

The deep-dive architecture guide lives in [`CLAUDE.md`](CLAUDE.md) — written
for LLMs but just as useful for humans who want the full map.

## Repo layout

```
crates/              Rust workspace (18 crates, one per bounded context)
  gothab-server/        binary — boots the HTTP and SSH servers
  gothab-api/           Axum routes + handlers
  gothab-git/           git object handling, protocol, blobstore
  gothab-ssh/           SSH server (russh)
  gothab-db/            sqlx models + queries
  gothab-auth/          sessions, tokens, permission checks
  gothab-ci/            workflow parsing, job dispatch, triggers
  gothab-runner/        runner binary (runs workflow jobs)
  gothab-agent/         firecracker-host agent
  gothab-search/        tantivy indexing + query
  gothab-tasks/         Redis Streams background task system
  gothab-hooks/         shared post-push hook pipeline
  gothab-storage/       tiered blob storage (local, R2)
  gothab-autoscale/     runner autoscaler controller
  gothab-firecracker-host/  Firecracker VM provisioning
  gothab-cli/           admin CLI
  gothab-common/        error types, config, shared utilities
frontend/            SolidJS app + Bun SSR server
packages/            @gothab/ui + shared TS packages
migrations/          PostgreSQL migrations (sqlx, immutable once promoted)
draft_migrations/    work-in-progress migrations (gitignored SQL)
scripts/             utilities (scripts/migration, etc.)
docker/              Dockerfile targets (caddy, ssr, server, runner)
docs/                operator + contributor docs
examples/            small standalone demos (pages-test-site, …)
```

## Development

Gothab is a hosted product, not a self-hosting project — but the code lives
here, and contributors need to run the stack. The local dev environment uses
[Tilt](https://tilt.dev) on top of `docker-compose.local.yml`:

```sh
tilt up
```

The UI is served on `http://localhost:8090`. PostgreSQL, Redis, the Rust
backend, the Bun SSR server, and Caddy all come up together and live-reload on
code changes.

Building the pieces directly (Rust stable, [pnpm](https://pnpm.io),
[Bun](https://bun.sh), PostgreSQL 14+):

```sh
# Backend
cargo build --release

# Frontend (client bundle + SSR bundle)
cd frontend && pnpm install && pnpm build
```

## Contributing

See `CLAUDE.md` for the architectural rules that keep SSR working, the data
layer coherent, and migrations safe. The headline ones:

- Never edit a file under `migrations/` once promoted — always add a new one
  (use `just migration-new` / `just migration-promote`, never `mv` by hand)
- Never import `onMount` / `onCleanup` from `solid-js` directly — use the SSR-
  safe wrappers in `frontend/src/lib/reactivity`
- Never use `Dynamic` from `solid-js/web` — use `Polymorphic` from `@gothab/ui`
- Prefer query hooks from `stores/*` over `createEffect` + manual fetch;
  `createEffect` is not awaited by SSR

Conventional commits. TypeScript (pnpm/bun) for greenfield, Rust for
performance-critical paths.

## License

All rights reserved.