| 1 | # Ferrenium |
| 2 | |
| 3 | A read-only Git repository browser, like cgit, as a single Rust daemon. It |
| 4 | serves every bare repository under one directory and keeps no state on disk. |
| 5 | |
| 6 | Pages: repo index, summary + README, tree, file (highlighted), raw, log |
| 7 | (path filter, message search), commit + diff, `.patch`, blame, refs, file |
| 8 | finder, `.tar.gz`/`.zip` snapshots, Atom feed. `git clone` over HTTPS |
| 9 | (read-only). |
| 10 | |
| 11 | ## Install |
| 12 | |
| 13 | On a Linux host with systemd (x86_64 or aarch64, glibc 2.28+): |
| 14 | |
| 15 | ```sh |
| 16 | curl -fsSL https://github.com/krolyxon/ferrenium/releases/latest/download/install.sh | sudo FERRENIUM_DOMAIN=git.example.com sh |
| 17 | ``` |
| 18 | |
| 19 | This: |
| 20 | |
| 21 | - downloads the latest release binary, verifies its checksum and installs it to `/usr/local/bin/ferrenium` |
| 22 | - creates the `git` user if it doesn't exist (home `/home/git`, shell `git-shell`) |
| 23 | - writes `/etc/ferrenium/ferrenium.toml` (never overwritten on later runs) |
| 24 | - installs `/etc/systemd/system/ferrenium.service` and runs `systemctl enable --now ferrenium` |
| 25 | |
| 26 | Variables: `FERRENIUM_DOMAIN` (fills `base_url` and clone URLs in a new |
| 27 | config), `FERRENIUM_USER` (default `git`), `FERRENIUM_VERSION` (e.g. |
| 28 | `v0.1.0`, default latest). |
| 29 | |
| 30 | Run the same command again to upgrade: it replaces the binary and unit |
| 31 | and restarts the service. To remove it: `… | sudo sh -s -- --uninstall`. |
| 32 | This keeps `/etc/ferrenium` and the repositories. |
| 33 | |
| 34 | ### The service |
| 35 | |
| 36 | It's a normal system service. The unit has `User=git`, so systemd starts it |
| 37 | as the repo owner. You don't need `su git` or `systemctl --user`. |
| 38 | |
| 39 | ```sh |
| 40 | sudo systemctl status ferrenium |
| 41 | sudo systemctl reload ferrenium # after editing the config |
| 42 | sudo journalctl -u ferrenium -f |
| 43 | sudo systemctl edit ferrenium # overrides; survive upgrades |
| 44 | ``` |
| 45 | |
| 46 | The unit is sandboxed: the filesystem is read-only, there are no |
| 47 | capabilities, a syscall filter applies, and only localhost may connect. |
| 48 | |
| 49 | ### Reverse proxy |
| 50 | |
| 51 | Ferrenium listens on `127.0.0.1:8080` (plain HTTP/1.1). Caddy: |
| 52 | |
| 53 | ```caddy |
| 54 | git.example.com { |
| 55 | reverse_proxy 127.0.0.1:8080 |
| 56 | } |
| 57 | ``` |
| 58 | |
| 59 | If Caddy runs in Docker, use `network_mode: host` so it can reach |
| 60 | `127.0.0.1`. |
| 61 | |
| 62 | ### Repositories |
| 63 | |
| 64 | Put bare repositories anywhere under `/home/git` (up to 3 levels deep). |
| 65 | Ferrenium picks up new repos and pushes within about a second. |
| 66 | |
| 67 | ```sh |
| 68 | sudo -u git git init --bare /home/git/project.git |
| 69 | git push git@git.example.com:project.git main # after adding your key to /home/git/.ssh/authorized_keys |
| 70 | ``` |
| 71 | |
| 72 | ## Configuration |
| 73 | |
| 74 | Edit `/etc/ferrenium/ferrenium.toml`. Every key is optional and unknown |
| 75 | keys are errors. The file lists all keys with their defaults |
| 76 | (`ferrenium example config` prints the same). To validate the config and |
| 77 | list the repositories it finds: |
| 78 | |
| 79 | ```sh |
| 80 | ferrenium check --config /etc/ferrenium/ferrenium.toml |
| 81 | ``` |
| 82 | |
| 83 | `listen`, `base_path`, `compression`, `cache.size_mb` and the `limits.*_parallel`/`max_requests` |
| 84 | settings need a restart; everything else applies on reload. |
| 85 | |
| 86 | Per-repository metadata comes from the first source that sets it: |
| 87 | |
| 88 | 1. `[[repo]]` in the config (`name`, `description`, `section`, `owner`, `hidden`, `readme`, `default_branch`) |
| 89 | 2. the repo's git config: `ferrenium.{description,owner,section,hidden,readme}`, or the gitweb/cgit keys |
| 90 | 3. the repo's `description` file |
| 91 | |
| 92 | ```sh |
| 93 | sudo -u git git -C /home/git/secret.git config ferrenium.hidden true |
| 94 | ``` |
| 95 | |
| 96 | ### Limits |
| 97 | |
| 98 | Defaults are sized for a small VPS: |
| 99 | |
| 100 | | Key | Default | | |
| 101 | |---|---|---| |
| 102 | | `limits.git_parallel` | CPUs, max 8 | concurrent git work | |
| 103 | | `limits.heavy_parallel` | 2 | concurrent blame / archive / clone / log search | |
| 104 | | `limits.heavy_wait_secs` | 10 | queue time for those before `503` | |
| 105 | | `limits.max_requests` | 512 | in-flight requests before `503` | |
| 106 | | `limits.request_timeout_secs` | 30 | until the response starts | |
| 107 | | `limits.diff_files` / `diff_lines` | 300 / 10000 | larger diffs are truncated | |
| 108 | | `ui.max_blob_kb` / `max_highlight_kb` | 1024 / 256 | larger files: raw link / no highlighting | |
| 109 | | `cache.size_mb` | 64 | in-memory cache | |
| 110 | |
| 111 | `/robots.txt` keeps crawlers off the expensive pages. Memory use at idle is |
| 112 | about 10 MB. |
| 113 | |
| 114 | ## Building from source |
| 115 | |
| 116 | Requires Rust 1.89+. |
| 117 | |
| 118 | ```sh |
| 119 | cargo build --release # target/release/ferrenium |
| 120 | ferrenium example config|systemd|caddy |
| 121 | ``` |
| 122 | |
| 123 | ## Development |
| 124 | |
| 125 | ```sh |
| 126 | cargo test # needs the git CLI |
| 127 | cargo test --release |
| 128 | cargo clippy --all-targets -- -D warnings |
| 129 | cargo run -- serve --config dev.toml |
| 130 | tools/gen-languages/gen.py # regenerate the Linguist language table |
| 131 | ``` |
| 132 | |
| 133 | To release: bump `version` in `Cargo.toml`, commit, then push a `vX.Y.Z` tag. |
| 134 | The `release` workflow tests, builds x86_64 and aarch64 binaries, and |
| 135 | publishes them with `install.sh` and `SHA256SUMS`. |
| 136 | |
| 137 | ## License |
| 138 | |
| 139 | GPL-3.0 (see `LICENSE`). Bundled fonts (Doto, Space Grotesk, Space Mono) |
| 140 | are licensed under the OFL; see `assets/fonts/OFL.txt`. Icons come from |
| 141 | Lucide (ISC license). |