Operations

This page covers running an Openhub instance day to day: first start, reverse proxies, backups, upgrades, administration without a UI, and troubleshooting. The project README has installation steps and the full configuration table.

First start checklist

1. Set OPENHUB_PUBLIC_URL to the exact URL people will use, such as https://git.example.com. Links, HTTP clone URLs, push hints, the cross-origin check and the cookie Secure flag all depend on it.
2. Set the SSH host and port with OPENHUB_SSH_HOST and OPENHUB_SSH_PORT if clients reach SSH on a different host or port from the one Openhub listens on. Docker port mapping is the usual reason.
3. Start the server and register the administrator account straight away. The first account becomes site administrator (see Security).
4. Add an SSH key in Settings → SSH keys, then check it with the command shown there (ssh -T -p 2222 git@host).
5. Set OPENHUB_DISABLE_REGISTRATION=true once everyone who needs an account has one, unless you intend to run an open instance.
6. Note the SSH host key fingerprint from the startup log (SSH host key fingerprint: SHA256:…) so users can verify it on first connect.

Logs

Openhub logs to stdout through tracing. Set the level with RUST_LOG:

Internal errors (HTTP 500) are logged with their full error chain. The user only sees a generic message.

Reverse proxy

Openhub speaks plain HTTP. Put a TLS-terminating proxy in front of it for the web port only; SSH goes straight to the SSH port.

Caddy:

git.example.com {
    reverse_proxy 127.0.0.1:3000
}

nginx:

server {
    listen 443 ssl;
    server_name git.example.com;
    # ssl_certificate …

    client_max_body_size 64m;          # git fetch negotiation for large repositories
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_buffering off;           # stream clones and archive downloads
    }
}

Then set OPENHUB_PUBLIC_URL=https://git.example.com. The cross-origin check accepts form posts whose Origin matches either the public URL or the Host header, so proxies that rewrite Host still work.

If you rate-limit at the proxy (recommended, see Security), cover POST /login, POST /register and /*/*/info/refs.

Backups

Everything lives in the data directory (see Architecture):

To restore: stop Openhub, put all three items back in one data directory, and start it again. The database and repos/ must come from the same point in time. A repository row without its directory, or a directory without its row, causes errors (see Data model → Invariants).

Upgrades

1. Back up the data directory.
2. Build or pull the new version. From source, run git pull && cargo build --release. With Docker, run docker compose build && docker compose up -d.
3. Start it. Pending database migrations run automatically at startup, before the servers listen.

Migrations only go forward. To roll back, restore the backup taken in step 1 and run the old version.

Repository maintenance

Openhub never runs git gc. git receive-pack runs git gc --auto after pushes by default, which keeps most repositories tidy. To compact a repository by hand, or to clean up objects left by failed web merges:

git --git-dir data/repos/<id>.git gc

To map a repository to its ID:

sqlite3 -readonly data/openhub.db \
  "SELECT r.id FROM repositories r JOIN users u ON u.id = r.owner_id WHERE u.username = 'alice' AND r.name = 'project';"

Run maintenance as the same user that runs Openhub, so file ownership stays correct. In Docker:

docker compose exec openhub git --git-dir /data/repos/<id>.git gc

Administration without a UI

Openhub has no admin pages. Do these tasks with sqlite3 against openhub.db, after taking a backup. Changes take effect immediately, and the server doesn't need restarting.

-- Make someone a site administrator (or set to 0 to remove)
UPDATE users SET is_admin = 1 WHERE username = 'bob';

-- Sign a user out everywhere
DELETE FROM sessions WHERE user_id = (SELECT id FROM users WHERE username = 'bob');

-- Revoke all of a user's SSH keys (stops them pushing)
DELETE FROM ssh_keys WHERE user_id = (SELECT id FROM users WHERE username = 'bob');

-- Transfer a repository to another user (the new owner must not already have a repository with that name)
UPDATE repositories SET owner_id = (SELECT id FROM users WHERE username = 'carol')
 WHERE id = 42;

Resetting a forgotten password. There's no reset flow. You can set a new hash made by any Argon2id tool that writes the standard PHC string format. For example, with the argon2 command-line tool (Debian package argon2):

printf '%s' 'new-password' | argon2 "$(openssl rand -hex 16)" -id -e
# → $argon2id$v=19$m=4096,t=3,p=1$…

UPDATE users SET password_hash = '$argon2id$v=19$…' WHERE username = 'bob';

Deleting a user. DELETE FROM users … removes their sessions, keys, repositories and collaborations, through cascades. It fails if they authored or merged pull requests, or wrote pull request events, in other users' repositories (see Data model → Deleting rows). Deleting their rows also doesn't remove their repositories' directories under repos/. Delete each repository in the web interface first, while signed in as an administrator.

Troubleshooting