Architecture

Openhub is one Rust process. It serves the web interface and git over HTTP on one port, and git over SSH on a second port. State is kept in two places:

• A SQLite database, for accounts, keys, repository metadata and pull requests.
• A directory of bare git repositories, for all code and history.

There are no background workers, queues or caches. Everything happens in response to a web request or an SSH session.

Components

   browser      git over HTTP             git over SSH
      │           │                        │
      ▼           ▼                        ▼
  ┌───────────────────────────┐   ┌───────────────────────────┐
  │ Web server (axum)         │   │ SSH server (russh)        │
  │ src/web/                  │   │ src/ssh.rs                │
  └─────────────┬─────────────┘   └─────────────┬─────────────┘
                │                               │
                └───────────────┬───────────────┘
                                ▼
  ┌───────────────────────────────────────────────────────────┐
  │ Shared core                                               │
  │   AppState (src/state.rs): Config, SQLite pool, access()  │
  │   libgit2, in process (src/git.rs, src/sync.rs)           │
  │   git child processes: upload-pack, receive-pack, archive │
  └─────────────┬───────────────────────────────┬─────────────┘
                ▼                               ▼
         <data>/openhub.db              <data>/repos/<id>.git
         SQLite database                bare repositories

Startup

main in src/main.rs:

1. Starts logging. The level comes from RUST_LOG and defaults to openhub=info.
2. Parses Config from flags and environment variables, then calls Config::normalize, which strips trailing slashes from the public URL.
3. Creates <data>/repos if it is missing.
4. Runs git --version. If git can't be run, startup fails.
5. Opens the database with db::connect:
   • Creates the database file if needed.
   • Turns on WAL mode, synchronous=NORMAL and foreign keys, with a 5-second busy timeout and a pool of up to 8 connections.
   • Applies any pending migrations.
6. Builds AppState and runs web::serve and ssh::serve together with tokio::select!.

If either server returns an error, the process exits. Ctrl-C shuts it down. On its first start, the SSH server generates <data>/ssh_host_ed25519_key (see Git transport).

Data directory

<data-dir>/                  default ./data, or /data in Docker
├── openhub.db               SQLite database (plus openhub.db-wal and openhub.db-shm while running)
├── ssh_host_ed25519_key     SSH host private key (mode 0600)
└── repos/
    ├── 1.git/               bare repository for repositories.id = 1
    └── 2.git/

A whole installation is this directory plus the binary. Back it up as a unit (see Operations).

libgit2 and the git executable

Openhub uses two git implementations, each for the jobs it handles best:

The wire protocol is left to the installed git, so protocol v2, shallow clones and future protocol changes come from the system package. Everything Openhub needs to inspect or compute is done with libgit2, which avoids parsing command output.

libgit2 is compiled into the binary from bundled C sources (git2 crate, default features off, so no OpenSSL or libssh2). The git executable is a runtime dependency, configurable with --git-bin.

Concurrency model

• Runtime. Openhub runs on a multi-threaded tokio runtime (#[tokio::main]).
• libgit2 calls are synchronous. Web handlers run them inside web::blocking, which wraps spawn_blocking, so they never stall the async workers. A git2::Repository is opened per request and never shared between threads.
• Database access is async through the sqlx pool. Handlers normally:
  1. Load the repository and check access (async).
  2. Do the git work (blocking).
  3. Render the page.
• Each SSH connection is its own russh handler (SshSession). Each git child process gets tasks that copy data between the SSH channel and the process's stdin, stdout and stderr.
• Child processes are started with tokio::process::Command and kill_on_drop(true), so a dropped connection kills its git process.
• Concurrent ref updates are serialised by git's own ref locking. Web merges use a compare-and-swap ref update, so a merge racing a push fails cleanly instead of overwriting it (see Pull requests).

How the main flows work

Viewing a file in the browser

1. The axum router matches /{owner}/{repo}/blob/{*rest} and calls code::blob.
2. ctx::middleware has already loaded the signed-in user from the session cookie into Ctx.
3. repo::load_repo looks up the repository by owner and name and calls AppState::access. If the user can't read it, the handler returns 404.
4. Inside web::blocking:
   • git::resolve splits rest into a ref and a path.
   • git::read_blob reads the file.
   • highlight::highlight_lines or markdown::render turns it into HTML.
5. The askama template renders. The middleware adds the security headers.

Pushing over SSH

1. russh authenticates the client key against ssh_keys.fingerprint.
2. The client runs git-receive-pack '/alice/project.git'. parse_command extracts the service, owner and name.
3. Openhub looks up the repository and checks write access.
4. It records the branch tips, then spawns git receive-pack <data>/repos/<id>.git and relays data between the client and the process.
5. When the process exits successfully:
   • sync::after_push updates pushed_at, fixes HEAD and refreshes open pull requests.
   • Push hints are printed as remote: lines.

Merging a pull request in the browser

1. pulls::merge checks write access and re-checks mergeability.
2. git::merge builds the new commits in memory with libgit2.
3. It moves the base branch with reference_matching, which only succeeds if the branch still points where it did when the merge started.
4. The database records the merge, and sync::refresh_pulls re-evaluates the repository's other open pull requests.

Design decisions

Scope

Openhub is git hosting only: repositories, code browsing, history, SSH keys, collaborators and pull requests. Issues, CI, wikis, releases, forks, organisations, webhooks, line-level review comments and HTTP push are out of scope. Discuss any of these before adding them.

When you change this

• New module: add it to the layout table in CLAUDE.md and to the components table above.
• New runtime dependency (another external program, say): add it to check_git-style startup checks, the Dockerfile runtime stage and the README requirements.