docs: make LAN access (GITLIB_BIND) easier to find for server installs

.env.example

@@ -1,11 +1,16 @@
 # Settings for `docker compose` (copy to .env, which is gitignored). Every line is optional.
 # Running the web app outside Docker (`npm run web`) uses apps/web/.env.example instead.
+#
+# Installing on a server / homelab VM and opening the app from another machine? Change GITLIB_BIND below to
+# 0.0.0.0 (the default 127.0.0.1 only answers on the server itself, so other machines get "connection refused"),
+# then run `docker compose up -d`. Allow the port in the VM's firewall if it has one. See docs/runbook.md.
 
 # --- Where things listen -----------------------------------------------------------------------------
 # Host port for the web app. 4000 by default so it stays clear of other local dev servers.
 GITLIB_PORT=4000
 # Interface the port is published on. 127.0.0.1 = this machine only (right for a Mac).
-# Use 0.0.0.0 on the homelab VM to reach it from the LAN. The app has no login: keep it off the internet.
+# Use 0.0.0.0 on the homelab VM to reach it from the LAN (REQUIRED for http://<server-ip>:4000 to work).
+# The app has no login: keep it off the internet.
 GITLIB_BIND=127.0.0.1
 
 # --- Files on the host -------------------------------------------------------------------------------

README.md

@@ -199,8 +199,9 @@ docker compose up -d --build       # http://localhost:4000
 ```
 
 The web app listens on **port 4000** (`GITLIB_PORT` to change it) and is published on `127.0.0.1` only, because it
-has **no login**. Set `GITLIB_BIND=0.0.0.0` to reach it over a trusted LAN, and keep it off the internet or behind
-an authenticating reverse proxy.
+has **no login**. On a server or homelab VM, set `GITLIB_BIND=0.0.0.0` in `.env` (then `docker compose up -d`) to
+reach it from other machines on a trusted LAN, and keep it off the internet or behind an authenticating reverse
+proxy. See [docs/runbook.md](docs/runbook.md#3-homelab-install) if the page still does not load.
 
 - Your repos are mounted read-only at `/home/node/git`, the default scan root for the container user. The host
   directory is `~/git` unless you set `GITLIB_REPOS` in `.env` (e.g. `GITLIB_REPOS=/Volumes/work/code`); run

docs/runbook.md

@@ -170,8 +170,20 @@ docker compose ps                         # both "healthy"
 curl -sI http://localhost:4000 | head -1
 ```
 
-Open `http://<vm-ip>:4000` from another machine. If it does not load, check the VM's firewall allows TCP 4000
-from your LAN (`sudo ufw allow from 192.168.1.0/24 to any port 4000` on Ubuntu).
+Open `http://<vm-ip>:4000` from another machine. If it does not load:
+
+- **"Connection refused" while `curl localhost:4000` works on the VM.** `GITLIB_BIND` is still its default
+  `127.0.0.1`, so the port is only published on the VM itself. `docker compose ps` shows `127.0.0.1:4000->4000/tcp`
+  instead of `0.0.0.0:4000->4000/tcp`. Fix it and recreate the container (a restart is not enough):
+
+  ```bash
+  sed -i 's/^GITLIB_BIND=.*/GITLIB_BIND=0.0.0.0/' .env
+  docker compose up -d
+  ```
+
+- **Times out.** The VM's firewall is blocking TCP 4000. Allow it from your LAN
+  (`sudo ufw allow from 192.168.1.0/24 to any port 4000` on Ubuntu).
+- **Wrong address.** Check the VM's current IP with `ip -4 addr`; a DHCP lease can change.
 
 **6. Make it survive reboots.** Containers use `restart: unless-stopped` and Docker starts at boot, so nothing
 more is needed. Confirm once with `sudo reboot`, then `docker compose ps`.