| d23464c0 Andy McCall ↶ |
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 |
|
| de505df5 Andy McCall ↶ |
12 |
Milestones 0.1 (browse), 0.2 (accounts and access) and 0.3 (proposals and |
| 13 |
review) are done: pages show |
| 19bb31ff Andy McCall ↶ |
14 |
trees, files, blame, history with the dependency graph, changes with diffs, |
| 15 |
comparisons, bookmarks, tags, conflicts, the trust policy and the push log; |
| 16 |
accounts sign in with a password and optional TOTP, create repositories and |
| 17 |
organisations, hold roles, mint scoped tokens for `oxy`, and link their |
| de505df5 Andy McCall ↶ |
18 |
Oxygen keys so signed changes are attributed to them; proposals offer a |
| 19 |
bookmark's changes for another with the resulting state, diff and conflicts |
| 20 |
computed before landing, comments anchored to atoms, approvals backed by |
| 21 |
seals, and landing from the hub or from `oxy proposal land`. Issues and the |
| 22 |
rest follow the milestones in the specification. |
| d23464c0 Andy McCall ↶ |
23 |
|
| 24 |
## Running |
| 25 |
|
| 26 |
``` |
| 27 |
cargo build --release |
| 28 |
target/release/oxygenhub --data /srv/oxygenhub init --base-url https://hub.example:7343 --self-signed |
| 19bb31ff Andy McCall ↶ |
29 |
target/release/oxygenhub --data /srv/oxygenhub admin user create andy --admin |
| d23464c0 Andy McCall ↶ |
30 |
target/release/oxygenhub --data /srv/oxygenhub serve |
| 31 |
``` |
| 32 |
|
| 19bb31ff Andy McCall ↶ |
33 |
Sign in, create a repository under `+ NEW` and a token under Settings › |
| 34 |
Tokens, then from any checkout: `oxy remote add hub https://hub.example:7343/andy/oxygen`, |
| 35 |
`oxy config remote.hub.token <token>` and `oxy push hub`. With a self-signed certificate, hand clients the CA with |
| d23464c0 Andy McCall ↶ |
36 |
`OXY_CA=<path>` or `oxy config remote.hub.ca <path>`. |
| 37 |
|
| 38 |
Configuration lives in `<data>/hub.toml` (spec §17.1) and every key can be |
| 39 |
overridden with `OXYHUB_<SECTION>_<KEY>`. |
| 40 |
|
| 41 |
## Layout |
| 42 |
|
| 43 |
``` |
| 44 |
crates/hub the binary: config, db (sqlx + migrations), repos (registry, locks, views), |
| 45 |
protocol (embedded oxy-server), web (pages), api (JSON), render (markdown, |
| 46 |
highlighting, diffs, graph) |
| 47 |
crates/hub-api the JSON API's types, shared with clients |
| 48 |
templates/ askama templates and the stylesheet |
| 49 |
assets/ vendored fonts, icons, the small progressive-enhancement script |
| 50 |
migrations/ under crates/hub; applied at start |
| 51 |
``` |
| 52 |
|
| 53 |
## Developing |
| 54 |
|
| 55 |
`make check` runs formatting, clippy with warnings as errors, and the tests. |
| 56 |
The tests use a real `oxy-core` client against a hub on a loopback port and |
| 57 |
never touch your own Oxygen configuration. |