# Ferrit

**Ferrit** is a minimal, self-hosted Git service written in Rust — a from-scratch,
independent reimplementation of the *core ideas* of a git forge (accounts,
repositories, a web code browser, and clone/push over HTTP). It is **not** derived
from the source of any existing project; only the general concept of a
"self-hosted git forge" is shared. The name (ferrous + git) and all code are
original.

## Features

- **User accounts** — registration & login, salted iterated-SHA-256 password
  hashing, cookie sessions.
- **Repositories** — create public or private bare repositories on disk.
- **Git smart-HTTP transport** — full `clone` / `fetch` / `push` support via a
  bridge to git's own `git http-backend` CGI.
  - Anonymous read of public repositories.
  - HTTP Basic authentication required for `push` and for any access to private
    repositories (only the owner is authorized).
- **Web code browser** — explore page, user profiles, repository view with file
  tree, blob viewer, and commit history.
- **Pure Rust** — no native-C dependencies. Built on `axum` + `tokio`. Repository
  metadata is persisted as JSON; git object storage is delegated to the system
  `git` binary (the same delegation strategy mature forges use).

## Requirements

- Rust (stable) and `git` available on `PATH`.

## Build & run

```sh
cargo build --release
./target/release/ferrit
```

Configuration via environment variables:

| Variable       | Default            | Meaning                       |
| -------------- | ------------------ | ----------------------------- |
| `FERRIT_ADDR`  | `127.0.0.1:3000`   | Listen address                |
| `FERRIT_DATA`  | `data`             | Data directory (db + repos)   |

Then open <http://127.0.0.1:3000>, register an account, and create a repository.

## Typical workflow

```sh
# after creating a repo "demo" in the web UI as user "alice":
git clone http://alice@127.0.0.1:3000/alice/demo.git
cd demo
echo "# demo" > README.md
git add README.md
git commit -m "first commit"
git push -u origin main      # prompts for the Ferrit password
```

## Architecture

| Module           | Responsibility                                             |
| ---------------- | ---------------------------------------------------------- |
| `src/store.rs`   | Users/repos data model, JSON persistence, password hashing |
| `src/gitio.rs`   | Wrappers around `git` for init/ls-tree/log/blob            |
| `src/githttp.rs` | Smart-HTTP CGI bridge to `git http-backend`, auth gating   |
| `src/web.rs`     | Routing, request handlers, server-side HTML rendering      |
| `src/main.rs`    | App state, sessions, server bootstrap                      |

## Layout on disk

```
data/
  db.json                     # users + repository metadata
  repos/<owner>/<name>.git/   # bare git repositories
```

## License

MIT