| 1 |
# Oxygenhub |
| 2 |
|
| 3 |
A forge for [Oxygen](../oxygen) repositories: hosting, browsing, review, |
| 4 |
issues and releases, in one Rust binary with one data directory. It works |
| 5 |
like GitHub where GitHub is right and differs where Oxygen's commutative |
| 6 |
model makes something better possible. The specification is |
| 7 |
[docs/spec.md](docs/spec.md); deployment notes are in |
| 8 |
[docs/deploy.md](docs/deploy.md). |
| 9 |
|
| 10 |
## Status |
| 11 |
|
| 12 |
Milestones 0.1 (browse), 0.2 (accounts and access), 0.3 (proposals and |
| 13 |
review), 0.4 (issues and notifications) and 0.5 (API, webhooks, checks) are |
| 14 |
done: pages show |
| 15 |
trees, files, blame, history with the dependency graph, changes with diffs, |
| 16 |
comparisons, bookmarks, tags, conflicts, the trust policy and the push log; |
| 17 |
accounts sign in with a password and optional TOTP, create repositories and |
| 18 |
organisations, hold roles, mint scoped tokens for `oxy`, and link their |
| 19 |
Oxygen keys so signed changes are attributed to them; proposals offer a |
| 20 |
bookmark's changes for another with the resulting state, diff and conflicts |
| 21 |
computed before landing, comments anchored to atoms, approvals backed by |
| 22 |
seals, and landing from the hub or from `oxy proposal land`; issues with |
| 23 |
labels, assignees, milestones, cross references and closing keywords; an |
| 24 |
inbox with watching, subscriptions, mentions and optional email; search |
| 25 |
over issues, proposals, repositories and accounts; a JSON API for all of |
| 26 |
it with scoped tokens, webhooks with signed deliveries and retries, and |
| 27 |
checks on state hashes that gate landing. Web edits, releases and the Git |
| 28 |
mirror follow in 0.6. |
| 29 |
|
| 30 |
## Running |
| 31 |
|
| 32 |
``` |
| 33 |
cargo build --release |
| 34 |
target/release/oxygenhub --data /srv/oxygenhub init --base-url https://hub.example:7343 --self-signed |
| 35 |
target/release/oxygenhub --data /srv/oxygenhub admin user create andy --admin |
| 36 |
target/release/oxygenhub --data /srv/oxygenhub serve |
| 37 |
``` |
| 38 |
|
| 39 |
Sign in, create a repository under `+ NEW` and a token under Settings › |
| 40 |
Tokens, then from any checkout: `oxy remote add hub https://hub.example:7343/andy/oxygen`, |
| 41 |
`oxy config remote.hub.token <token>` and `oxy push hub`. With a self-signed certificate, hand clients the CA with |
| 42 |
`OXY_CA=<path>` or `oxy config remote.hub.ca <path>`. |
| 43 |
|
| 44 |
Configuration lives in `<data>/hub.toml` (spec §17.1) and every key can be |
| 45 |
overridden with `OXYHUB_<SECTION>_<KEY>`. |
| 46 |
|
| 47 |
## Layout |
| 48 |
|
| 49 |
``` |
| 50 |
crates/hub the binary: config, db (sqlx + migrations), repos (registry, locks, views), |
| 51 |
protocol (embedded oxy-server), web (pages), api (JSON), render (markdown, |
| 52 |
highlighting, diffs, graph) |
| 53 |
crates/hub-api the JSON API's types, shared with clients |
| 54 |
templates/ askama templates and the stylesheet |
| 55 |
assets/ vendored fonts, icons, the small progressive-enhancement script |
| 56 |
migrations/ under crates/hub; applied at start |
| 57 |
``` |
| 58 |
|
| 59 |
## Developing |
| 60 |
|
| 61 |
`make check` runs formatting, clippy with warnings as errors, and the tests. |
| 62 |
The tests use a real `oxy-core` client against a hub on a loopback port and |
| 63 |
never touch your own Oxygen configuration. |