# OxygenHub

A forge for [Oxygen](../oxygen) repositories: hosting, browsing, review,

issues and releases, in one Rust binary with one data directory. It works

like GitHub where GitHub is right and differs where Oxygen's commutative

model makes something better possible. The specification is

[docs/spec.md](docs/spec.md); deployment notes are in

[docs/deploy.md](docs/deploy.md).

## Status

Milestones 0.1 (browse), 0.2 (accounts and access), 0.3 (proposals and

review), 0.4 (issues and notifications), 0.5 (API, webhooks, checks) and

0.6 (web edits, releases, mirror, code search) are done: pages show

trees, files, blame, history with the dependency graph, changes with diffs,

comparisons, bookmarks, tags, conflicts, the trust policy and the push log;

accounts sign in with a password and optional TOTP, create repositories and

organisations, hold roles, mint scoped tokens for `oxy`, and link their

Oxygen keys so signed changes are attributed to them; proposals offer a

bookmark's changes for another with the resulting state, diff and conflicts

computed before landing, comments anchored to atoms, approvals backed by

seals, and landing from the hub or from `oxy proposal land`; issues with

labels, assignees, milestones, cross references and closing keywords; an

inbox with watching, subscriptions, mentions and optional email; search

over issues, proposals, repositories and accounts; a JSON API for all of

it with scoped tokens, webhooks with signed deliveries and retries, and

checks on state hashes that gate landing; editing and conflict resolution

in the browser, signed by the hub as your delegate; releases with assets

and source archives; a read-only Git mirror for Git-only tools; and code

search. The runner follows in 0.7.

**Drops** (oxygenhub#279) are gist-like snippets of one or more files, each

its own small Oxygen repository: made and edited in the browser, through

the API or with `oh drop`, every edit a signed change with history,

cloned and pushed with `oxy`, public or secret (listed nowhere, readable

by anyone with the address), and never listed among your repositories.

See `/drops` and docs/spec.md §4.5.

## Install oh

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.

- **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).

- **Other Linux:** unpack `oh-VERSION-linux-x86_64.tar.gz` (or `-linux-arm64`) and put `oh` on your `PATH`.

- **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`.

- **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.

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).

Check a download against the release's `SHA256SUMS` with `sha256sum -c SHA256SUMS --ignore-missing`.

## Running

```

cargo build --release

target/release/oxygenhub --data /srv/oxygenhub init --base-url https://hub.example:7343 --self-signed

target/release/oxygenhub --data /srv/oxygenhub admin user create andy --admin

target/release/oxygenhub --data /srv/oxygenhub serve

```

Sign in, create a repository under `+ NEW` and a token under Settings ›

Tokens, then from any checkout: `oxy remote add hub https://hub.example:7343/andy/oxygen`,

`oxy config remote.hub.token <token>` and `oxy push hub`. With a self-signed certificate, hand clients the CA with

`OXY_CA=<path>` or `oxy config remote.hub.ca <path>`.

Configuration lives in `<data>/hub.toml` (spec §17.1) and every key can be

overridden with `OXYHUB_<SECTION>_<KEY>`.

## Layout

```

crates/hub        the binary: config, db (sqlx + migrations), repos (registry, locks, views),

                  protocol (embedded oxy-server), web (pages), api (JSON), render (markdown,

                  highlighting, diffs, graph)

crates/hub-api    the JSON API's types, shared with clients

templates/        askama templates and the stylesheet

assets/           vendored fonts, icons, the small progressive-enhancement script

migrations/       under crates/hub; applied at start

```

## Developing

`make check` runs the changelog check, formatting, clippy with warnings as errors, and the tests.

**Changelog:** a commit that changes code adds a line under `## Unreleased` in CHANGELOG.md (Added, Changed, Fixed or Security, with the issue number); versions change only at release. `scripts/changelog-check.sh [PATH...]` checks it for the paths a commit takes (the working copy's changes without any) and runs in the gate; `NO_CHANGELOG=1` for code changes users won't notice.

The tests use a real `oxy-core` client against a hub on a loopback port and

never touch your own Oxygen configuration.

## oxygenflow and oxygen as pinned subrepos

The hub builds against `deps/oxygenflow`, a subrepo (`oxy submodule`) pinned to an exact state, and against the oxygen that oxygenflow pins in turn, `deps/oxygenflow/deps/oxygen`. So there is one oxygen, the one oxygenflow was built and tested with, every build says which it used, and OxygenFlow can build the hub without network.

- **Newer code:** push oxygen, run `make pins` in oxygenflow and push it, then run `make pins` here. The next commit records the new pin.

- **Formatting:** format only this workspace, with `cargo fmt -p oxygenhub -p hub-api`. `--all` also reaches the path dependencies in `deps/`, which have their own formatting.

- **Fresh clone:** `oxy submodule update --init` here and in `deps/oxygenflow` fetches them.