Use host networking for compose OAuth callbacks

.env.example

@@ -4,8 +4,8 @@ RDP_PASSWORD=
 # Leave blank to reuse the RDP credentials for Guacamole.
 GUAC_USER=
 GUAC_PASSWORD=
-HATCH_HTTPS_PORT=443
-HATCH_HTTPS_HOST_PORT=8443
+# Docker Compose uses host networking, so this is the host listener port.
+HATCH_HTTPS_PORT=8443
 HATCH_START_URL=about:blank
 # Maps remote Super/Cmd-style shortcuts to Linux Ctrl shortcuts.
 HATCH_MAC_SHORTCUTS=1

INSTALL.md

@@ -154,15 +154,15 @@ docker compose ps
 docker compose logs hatch
 ```
 
-The compose file maps host port `${HATCH_HTTPS_HOST_PORT:-8443}` to container port `${HATCH_HTTPS_PORT:-443}`.
+The compose file uses host networking and listens on `${HATCH_HTTPS_PORT:-8443}` directly on the host.
 
 Stop Hatch with:
 
 ```bash
 docker compose down
 ```
 
-Use the explicit `docker run --network host` command for OAuth callback mode because compose port mappings are ignored when host networking is enabled.
+The compose file uses host networking for OAuth callback mode. Open `https://<server>:8443/guacamole/` unless you set a different `HATCH_HTTPS_PORT`. Hatch listens on `HATCH_HTTPS_PORT` directly on the host. This is required for callback URLs such as `http://127.0.0.1:40397/callback/...` because Chromium is running inside the Hatch container and must see the Linux host's loopback interface.
 
 ## Troubleshooting
 

PRD.md

@@ -18,6 +18,7 @@ Hatch must provide browser-based desktop access through HTTPS from the container
 - The generated Guacamole credentials are printed to container logs and usable when the container is started detached.
 - Docker users can map any host port to container port `443`, for example `-p 8443:443`.
 - Host-network OAuth callback mode remains documented for cases where Chromium must reach a callback listener on host loopback.
+- Docker Compose uses host-network OAuth callback mode, listens on host port `8443` by default, and does not rely on ignored port mappings.
 - The default desktop session maps remote Super/Mac-style shortcuts such as paste, copy, and address-bar focus to the Linux Ctrl shortcuts expected by Chromium, with an environment variable to disable the mapping.
 - Default Docker and Docker Compose starts do not show Chromium's unsupported `--no-sandbox` warning.
 - The README presents the HTTPS Guacamole flow as the primary quickstart and keeps Docker Compose as a lower-priority option.

README.md

@@ -114,13 +114,13 @@ docker compose up -d --build
 docker compose logs hatch
 ```
 
-The compose file maps host port `${HATCH_HTTPS_HOST_PORT:-8443}` to container port `${HATCH_HTTPS_PORT:-443}`. Stop it with:
+The compose file uses host networking and listens on `${HATCH_HTTPS_PORT:-8443}` directly on the host. Stop it with:
 
 ```bash
 docker compose down
 ```
 
-For host-network OAuth callback mode, prefer the `docker run --network host` command above because compose port mappings are not used with host networking.
+The compose file uses host networking for OAuth callback mode. In this mode Chromium's `127.0.0.1` is the Linux host loopback, so dynamic callback URLs such as `http://127.0.0.1:40397/callback/...` can reach the listener started by the OAuth tool. Docker ignores compose port mappings when host networking is enabled, so Hatch listens on `${HATCH_HTTPS_PORT:-8443}` directly on the host.
 
 ## E2E Guacamole Test
 

docker-compose.yml

@@ -5,15 +5,14 @@ services:
     image: hatch:local
     container_name: hatch
     restart: unless-stopped
-    ports:
-      - "${HATCH_HTTPS_HOST_PORT:-8443}:${HATCH_HTTPS_PORT:-443}"
+    network_mode: host
     shm_size: "1gb"
     environment:
       RDP_USER: ${RDP_USER:-oauth}
       RDP_PASSWORD: ${RDP_PASSWORD:-}
       GUAC_USER: ${GUAC_USER:-}
       GUAC_PASSWORD: ${GUAC_PASSWORD:-}
-      HATCH_HTTPS_PORT: ${HATCH_HTTPS_PORT:-443}
+      HATCH_HTTPS_PORT: ${HATCH_HTTPS_PORT:-8443}
       HATCH_START_URL: ${HATCH_START_URL:-about:blank}
       HATCH_MAC_SHORTCUTS: ${HATCH_MAC_SHORTCUTS:-1}
       CHROMIUM_EXTRA_FLAGS: ${CHROMIUM_EXTRA_FLAGS:-}