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.

Running under systemd

packaging/linux/ holds a systemd unit (openhub.service) and an installer (install.sh). scripts/deploy-server.sh user@host copies the checkout to the machine, builds it there and runs the installer over SSH (see the README).

The unit listens for the web interface on 127.0.0.1:3000 and for SSH on 0.0.0.0:2222. Override either in /etc/default/openhub.

Each run of install.sh:

1. Stops the service and copies openhub.db into backups/<timestamp>/ in the data directory, keeping the last five. Repositories aren't copied.
2. Swaps the binary, starts the service, and waits up to 20 seconds for the web interface to answer.
3. If it doesn't answer, puts the previous binary back. If the new version had already migrated the database, restore the snapshot as described in Upgrades.

Power cuts. The unit restarts the server whenever it exits and never stops retrying (Restart=always, StartLimitIntervalSec=0). It also sets git's core.fsync=committed through GIT_CONFIG_* variables, so a push's objects and refs are on disk before git reports success. SQLite runs in WAL mode with synchronous=NORMAL, so a power cut can lose the last few database writes but doesn't corrupt the database.

Sandboxing. The unit uses ProtectSystem=strict, so the server can only write to /var/lib/openhub. If you move the data directory, also allow it with ReadWritePaths= in a drop-in (sudo systemctl edit openhub).

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
    }
}

Cloudflare Tunnel (an ingress rule in the cloudflared config, then cloudflared tunnel route dns <tunnel> git.example.com):

ingress:
  - hostname: git.example.com
    service: http://127.0.0.1:3000
  - service: http_status:404

A tunnel carries only the web interface. Clients still need to reach the SSH port another way, for example on the local network or through a forwarded port. Set OPENHUB_SSH_HOST to the address they use.

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. Under systemd, run scripts/deploy-server.sh user@host again: it snapshots the database itself, and puts the old binary back if the new one fails to start (see Running under systemd).
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