GitHop/docs/production-deployment.md

Production deployment

Run the Compose stack behind an HTTPS reverse proxy. Keep the Gitea HTTP port and Hop control-plane port bound to loopback; only publish Gitea's SSH port if the deployment has a DNS-only hostname that can reach it without an HTTP proxy.

Start from .env.example, replace every secret, and set at least:

GITEA_DOMAIN=git.example.com
GITEA_ROOT_URL=https://git.example.com/
GITEA_HTTP_BIND=127.0.0.1
HOP_HTTP_BIND=127.0.0.1
GITEA_SSH_BIND=127.0.0.1
GITEA_DISABLE_SSH=true
GITEA_DISABLE_REGISTRATION=true
GITEA_ACTIONS_ENABLED=false

Start the services and install the Hop-native Gitea assets:

docker compose --env-file .env up --build -d
./deploy/gitea/install-hop-native.sh

The reverse proxy should forward the public hostname to the configured GITEA_HTTP_BIND:GITEA_HTTP_PORT, preserve the Host header, and set X-Forwarded-Proto to https. It must also proxy /hop/ to the Hop control plane, preserving the browser's Gitea session cookie. This lets the Prompts view check the viewer's repository access before returning potentially sensitive prompt text.

The control plane verifies the browser session through Gitea's protected web settings route. Hop's custom Gitea header renders the active account's immutable user ID into that protected response, so browser-session verification does not depend on Gitea's token-only /api/v1/user endpoint or GITEA_API_TOKEN.

For nginx, the control-plane location should precede the Gitea catch-all:

location /hop/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Cookie $http_cookie;
}

Persistent repository and database data live in the named Compose volumes.