| 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 |
Milestone 0.1 (browse): repositories are created by an administrator and |
| 13 |
filled by `oxy push`; the pages show trees, files, blame, history with the |
| 14 |
dependency graph, changes with diffs, comparisons, bookmarks, tags, |
| 15 |
conflicts, the trust policy and the push log. Accounts, proposals, issues |
| 16 |
and the rest follow the milestones in the specification. |
| 17 |
|
| 18 |
## Install oh |
| 19 |
|
| 20 |
Builds for Linux, macOS and Windows are on the [releases page](https://oxygenhub.io/andymccall/oxygenhub/releases). These are early releases: the macOS and Windows builds are not signed and have had little testing. |
| 21 |
|
| 22 |
- **Debian, Ubuntu and other Linux with apt** (x86_64 or arm64): download `oh_VERSION_amd64.deb` (or `_arm64.deb`) and run `sudo apt install ./oh_VERSION_amd64.deb`. It needs glibc 2.28 or later (Debian 10, Ubuntu 20.04 and newer). |
| 23 |
- **Other Linux:** unpack `oh-VERSION-linux-x86_64.tar.gz` (or `-linux-arm64`) and put `oh` on your `PATH`. |
| 24 |
- **macOS** (Apple Silicon or Intel): unpack `oh-VERSION-macos-arm64.tar.gz` (or `-macos-x86_64`), then `xattr -d com.apple.quarantine oh`, since the build is not notarised, and put it on your `PATH`. |
| 25 |
- **Windows:** unzip `oh-VERSION-windows-x86_64.zip` and put the folder on your `PATH`. SmartScreen may warn on first run, since the build is not signed. |
| 26 |
|
| 27 |
Sign in with `oh auth login --with-hub https://oxygenhub.io`; the commands are in `docs/oh.md`. `oh` works alongside `oxy`, from [Oxygen's releases](https://oxygenhub.io/andymccall/oxygen/releases). |
| 28 |
|
| 29 |
Check a download against the release's `SHA256SUMS` with `sha256sum -c SHA256SUMS --ignore-missing`. |
| 30 |
|
| 31 |
## Running |
| 32 |
|
| 33 |
``` |
| 34 |
cargo build --release |
| 35 |
target/release/oxygenhub --data /srv/oxygenhub init --base-url https://hub.example:7343 --self-signed |
| 36 |
target/release/oxygenhub --data /srv/oxygenhub admin repo create andy/oxygen --description "The VCS" |
| 37 |
target/release/oxygenhub --data /srv/oxygenhub serve |
| 38 |
``` |
| 39 |
|
| 40 |
Then from any checkout: `oxy remote add hub https://hub.example:7343/andy/oxygen` |
| 41 |
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. |