From 093116f5e14cc21c31ca6f8ccb677dc6651f347f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 18:23:26 +0200
Subject: [PATCH] docs(gateway): document forge httpPort, sshPort,
 openFirewall, rootUrl options
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "hive-forge container shape" section described the container
isolation model but omitted the port and firewall knobs that operators
need when exposing forge externally or overriding the Forgejo ROOT_URL.

Add two subsections:

"Network and port configuration" — covers httpPort (default 3000),
sshPort (default 2222), and openFirewall (default false, was previously
true — breaking change note included). Explains the shared-netns
rationale for why openFirewall is safe to leave off for agent use but
must be set for browser/external-git-client access. Clarifies that
forge.behindGateway obviates forge.openFirewall for HTTP reach.

"rootUrl override" — documents forge.rootUrl (default null) with the
auto-derivation table (behindGateway ? http://domain/ : http://domain:port/)
and explains when to override (TLS, https:// clone URLs, bespoke shapes).
Notes the auto-derivation always produces http://, so TLS operators must
set rootUrl explicitly.
---
 docs/gateway.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/gateway.md b/docs/gateway.md
index 592a5269..70a0c019 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -306,6 +306,62 @@ State lives at `/var/lib/nixos-containers/hive-forge/var/lib/forgejo/`
 and survives container restart / host reboot. To wipe, destroy the
 container.
 
+### Network and port configuration
+
+```nix
+services.hyperhive.forge = {
+  httpPort   = 3000;   # default — HTTP listener; outside hyperhive's 7000/8100-8999 range
+  sshPort    = 2222;   # default — git-over-SSH; kept off 22 so it doesn't collide with the host openssh
+  openFirewall = false; # default — expose httpPort + sshPort to the host firewall
+};
+```
+
+`httpPort` (default **3000**) is the port Forgejo's HTTP server binds to.
+It sits outside hyperhive's reserved ranges (dashboard 7000,
+agents 8100–8999) so a default install has no port fights. Change it
+only if you already have another process bound to 3000.
+
+`sshPort` (default **2222**) is the port Forgejo's built-in SSH server
+uses for `git clone/push/pull` over SSH (`git@<domain>:owner/repo.git`
+via `-p 2222`). Port 22 is left alone on the host for openssh.
+
+`openFirewall` (default **false**) controls whether `httpPort` and
+`sshPort` are opened in the host firewall. Off by default (secure by
+default): every agent container reaches Forgejo at `localhost:<httpPort>`
+via the shared host netns without a firewall hole. Flip to `true` when
+you need:
+- The operator's browser to reach `http://<host>:<httpPort>/` directly
+  (not behind the gateway).
+- External git clients that push/pull via SSH directly to the host.
+
+**Breaking change**: `openFirewall` used to default to `true`. If
+external forge access stopped working after a recent upgrade, add
+`services.hyperhive.forge.openFirewall = true;` to your host config.
+Forgejo served through the gateway (`forge.behindGateway = true`) does
+not need `openFirewall` — the gateway's own `openFirewall` option covers
+that path.
+
+### `rootUrl` override
+
+```nix
+services.hyperhive.forge.rootUrl = "https://forge.example.com/";
+```
+
+`rootUrl` (default **null**) overrides the Forgejo `ROOT_URL` that is
+auto-derived from `forge.domain` + gateway state. The auto-derivation
+covers most cases:
+
+| Shape | Auto-derived `ROOT_URL` |
+|---|---|
+| `behindGateway = true` | `http://<forge.domain>/` (port suffix omitted when `gateway.port == 80`) |
+| `behindGateway = false` | `http://<forge.domain>:<httpPort>/` |
+
+The auto-derivation always uses `http://`. Set `rootUrl` explicitly when
+you need `https://` (e.g. behind a TLS-terminating reverse proxy or when
+`selfSignedTls = true` and clone URLs must carry `https://`), or when
+`forge.domain` resolves differently from the public URL. Must end with
+`/` (Forgejo requirement; an assertion enforces this).
+
 ## Per-agent static frontend split
 
 When `services.hyperhive.frontend` is configured, hive-c0re injects