Merge pull request #5 from VocaHQ/fix/compose-env-passthrough-and-config-drift

fix: pass gateway settings through Compose and reconcile env docs

Author: Mr-Sunglasses

.dockerignore

@@ -9,3 +9,19 @@ data
 *.sqlite*
 *.wav
 *.log
+
+# A populated .env holds the bearer token. No Dockerfile copies it, but keeping
+# it out of the build context means it is never sent to the daemon or captured
+# in a build cache layer.
+.env
+.envrc
+
+# Never needed by a build stage; .git in particular is large and changes on
+# every commit, which would invalidate the context for no reason.
+.git
+.gitignore
+.github
+docs
+scripts
+LICENSE
+justfile

.env.example

@@ -13,6 +13,10 @@
 # Bearer token the phone apps present on every request. At least 32 characters.
 # Compose passes it to the container as a secret, not as an environment
 # variable. Generate one with: openssl rand -hex 32
+#
+# Fill this in, or append a second VOCAGATEWAY_TOKEN= line as shown above —
+# Compose uses the last assignment when a key repeats, so the appended value
+# wins over this empty placeholder.
 VOCAGATEWAY_TOKEN=
 
 # Host interface and port Docker publishes the gateway on.
@@ -29,10 +33,36 @@ VOCAGATEWAY_PUBLISH_PORT=8765
 # it.
 #VOCAGATEWAY_NETWORK_MODE=host
 
+# Address the pairing QR should encode. On the default bridge network the
+# container only sees its own private bridge IP (172.x), never the host's LAN
+# NIC, so auto-discovery cannot produce a phone-reachable address — set this to
+# the URL the phone should actually use. This is the alternative to
+# VOCAGATEWAY_NETWORK_MODE=host, and the only option on Docker Desktop.
+# VOCAGATEWAY_PAIRING_URL is an accepted alias, checked second.
+#VOCAGATEWAY_PUBLIC_URL=http://192.168.1.20:8765
+
 # Use a prebuilt multi-architecture image instead of building the local tag.
 #VOCAGATEWAY_IMAGE=ghcr.io/your-user/vocaphone-gateway:latest
 
 # Serve the Swagger UI at /docs and the schema at /openapi.json. Off by
 # default: the schema and UI are extra surface area, so enable this only for
 # local development.
 #VOCAGATEWAY_DEBUG=true
+
+# Listener inside the container. Only meaningful under
+# VOCAGATEWAY_NETWORK_MODE=host, where the container binds the host directly and
+# VOCAGATEWAY_PUBLISH_HOST/_PORT are discarded; on the default bridge network
+# the gateway must keep listening on all container interfaces for the published
+# port to reach it.
+#VOCAGATEWAY_BIND_HOST=0.0.0.0
+#VOCAGATEWAY_PORT=8765
+
+# Pin an engine instead of letting `auto` pick the first runnable one. The
+# container can run sherpa-onnx, faster-whisper, moonshine, and whisper.cpp;
+# vocamac, handy, whisperkit, and mlx-audio are macOS-only and rejected here.
+#VOCAGATEWAY_ENGINE=auto
+
+# How long a failed session's audio is kept so the phone can retry, and whether
+# audio is deleted immediately after a successful transcription.
+#VOCAGATEWAY_RETENTION_HOURS=24
+#VOCAGATEWAY_DELETE_SUCCESSFUL_AUDIO=true

Dockerfile

@@ -61,5 +61,5 @@ USER vocaphone
 EXPOSE 8765
 VOLUME ["/data"]
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/health/live', timeout=3)"]
+  CMD ["python", "-c", "import os, urllib.request; port = os.environ.get('VOCAGATEWAY_PORT', '8765'); urllib.request.urlopen(f'http://127.0.0.1:{port}/health/live', timeout=3)"]
 ENTRYPOINT ["vocaphone-server"]

Dockerfile.cuda

@@ -56,5 +56,5 @@ USER vocaphone
 EXPOSE 8765
 VOLUME ["/data"]
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
-  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/health/live', timeout=3)"]
+  CMD ["python", "-c", "import os, urllib.request; port = os.environ.get('VOCAGATEWAY_PORT', '8765'); urllib.request.urlopen(f'http://127.0.0.1:{port}/health/live', timeout=3)"]
 ENTRYPOINT ["vocaphone-server"]

Dockerfile.vulkan

@@ -56,5 +56,5 @@ USER vocaphone
 EXPOSE 8765
 VOLUME ["/data"]
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
-  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/health/live', timeout=3)"]
+  CMD ["python", "-c", "import os, urllib.request; port = os.environ.get('VOCAGATEWAY_PORT', '8765'); urllib.request.urlopen(f'http://127.0.0.1:{port}/health/live', timeout=3)"]
 ENTRYPOINT ["vocaphone-server"]

README.md

@@ -162,18 +162,27 @@ CLI. The same Dockerfile builds on Linux `amd64` and `arm64`.
 
 ```sh
 umask 077
-printf 'VOCAGATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env
-printf 'VOCAGATEWAY_PUBLISH_HOST=127.0.0.1\n' >> .env
-printf 'VOCAGATEWAY_PUBLISH_PORT=8765\n' >> .env
+cp .env.example .env
+printf 'VOCAGATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" >> .env
 docker compose up --detach --build
 docker compose ps
 curl --fail http://127.0.0.1:8765/health/live
 ```
 
+[`.env.example`](.env.example) is the annotated template: it already sets the
+loopback publication defaults and comments out every other supported setting,
+so starting from it is how you find out what is tunable. Appending the token
+overrides the empty `VOCAGATEWAY_TOKEN=` placeholder it ships with — Compose
+takes the last assignment of a repeated key.
+
 The token is provided as a Compose secret rather than a container environment
 variable. Models, configuration, and the SQLite database persist in the
 `vocagateway_vocagateway-data` named volume mounted at `/data`.
 
+Before pairing a phone, read the bridge-network note below: on the default
+network the QR cannot auto-discover a reachable address, and
+`VOCAGATEWAY_PUBLIC_URL` in `.env` is what fixes it.
+
 The container is live before a model is installed, so `/health/ready` initially
 returns `503`. Open the WebUI, enter the token from `.env`, download/select a
 recommended sherpa-onnx, Moonshine, or faster-whisper model, and check again:
@@ -190,12 +199,16 @@ firewall. Never expose port 8765 to the public internet.
 The default bridge network also hides the host's real LAN address from the
 gateway's own address auto-discovery (used for the pairing QR): the container
 only ever sees its private bridge IP, not the host's Wi-Fi/Ethernet interface.
-On Linux Docker Engine (not Docker Desktop on macOS/Windows), set
-`VOCAGATEWAY_NETWORK_MODE=host` in `.env` instead so the container shares the
-host's network namespace and discovery finds the real `192.168.x.x` address.
-This ignores `VOCAGATEWAY_PUBLISH_HOST`/`PORT` — the container binds directly on
-the host per `VOCAGATEWAY_BIND_HOST`/`VOCAGATEWAY_PORT`, so lock down port 8765
-with the host firewall first.
+Two ways out, both set in `.env`:
+
+- `VOCAGATEWAY_PUBLIC_URL=http://192.168.1.20:8765` names the address the phone
+  should use and skips discovery entirely. This works everywhere, including
+  Docker Desktop on macOS and Windows.
+- `VOCAGATEWAY_NETWORK_MODE=host`, on Linux Docker Engine only, shares the
+  host's network namespace so discovery finds the real `192.168.x.x` address by
+  itself. This ignores `VOCAGATEWAY_PUBLISH_HOST`/`PORT` — the container binds
+  directly on the host per `VOCAGATEWAY_BIND_HOST`/`VOCAGATEWAY_PORT`, so lock
+  down port 8765 with the host firewall first.
 
 ## WebUI
 
@@ -387,14 +400,28 @@ uv run vocaphone-server
 | `VOCAGATEWAY_CONFIG_FILE` | `~/.config/vocagateway/config.json` | `/data/config/config.json` | WebUI engine/model choice |
 | `VOCAGATEWAY_ENGINE` | `auto` | `auto` | `auto`, `vocamac`, `handy`, `mlx-audio`, `whisperkit`, `sherpa-onnx`, `faster-whisper`, `moonshine`, or `whisper.cpp` |
 | `VOCAGATEWAY_WHISPER_BINARY` | `/opt/homebrew/bin/whisper-cli` | `/usr/local/bin/whisper-cli` | `whisper.cpp` executable |
-| `VOCAGATEWAY_WHISPER_MODEL` | base model path | base model path | Fallback `whisper.cpp` model |
+| `VOCAGATEWAY_WHISPER_MODEL` | `~/.local/share/whisper.cpp/models/ggml-base.en.bin` | same, and normally absent | Fallback `whisper.cpp` model used only when no model is selected in the WebUI |
 | `VOCAGATEWAY_WHISPERKIT_BINARY` | `whisperkit-cli` | unavailable | WhisperKit executable |
 | `VOCAGATEWAY_VOCAMAC_APP` | `/Applications/VocaMac.app` | unavailable | Optional VocaMac app bundle |
 | `VOCAGATEWAY_VOCAMAC_MODEL` | unset | unset | Pin a VocaMac model instead of following the app's choice |
+| `VOCAGATEWAY_HANDY_BINARY` | `/Applications/Handy.app/Contents/MacOS/handy` | unavailable | Optional Handy application binary |
+| `VOCAGATEWAY_HANDY_MODEL` | unset | unset | Pin a Handy model (`owner/repository/model.gguf`) |
+| `VOCAGATEWAY_HANDY_FALLBACK_MODEL` | `handy-computer/whisper-base-gguf/whisper-base-Q8_0.gguf` | unavailable | Model used when the pinned Handy model is missing |
 | `VOCAGATEWAY_RETENTION_HOURS` | `24` | `24` | Failed-session retry retention |
 | `VOCAGATEWAY_DELETE_SUCCESSFUL_AUDIO` | `true` | `true` | Delete source/normalized audio after success |
-
-Compose-specific variables live in `.env`:
+| `VOCAGATEWAY_PUBLIC_URL` | unset | unset | Address the pairing QR encodes, overriding auto-discovery |
+| `VOCAGATEWAY_PAIRING_URL` | unset | unset | Alias for `VOCAGATEWAY_PUBLIC_URL`, checked second |
+| `VOCAGATEWAY_DEBUG` | `false` | `false` | Serve the Swagger UI at `/docs` and the schema at `/openapi.json` |
+
+Under Compose, `VOCAGATEWAY_BIND_HOST`, `PORT`, `ENGINE`, `RETENTION_HOURS`,
+`DELETE_SUCCESSFUL_AUDIO`, `PUBLIC_URL`, `PAIRING_URL`, and `DEBUG` are read
+from `.env` and passed into the container. `VOCAGATEWAY_TOKEN` becomes a
+Compose secret at `/run/secrets/vocagateway_token` rather than an environment
+variable. The remaining paths and binaries are fixed by the image to their
+container locations, and the macOS-only engine variables have no effect there.
+
+Compose-only variables, which the gateway process itself never reads, also live
+in `.env`:
 
 | Variable | Default | Purpose |
 | --- | --- | --- |

compose.yaml

@@ -1,5 +1,26 @@
 name: vocagateway
 
+# Every gateway service takes the same settings; only the build and the device
+# wiring differ per profile. Keeping them in one anchor means a variable added
+# here reaches all four services instead of three of them.
+x-gateway-environment: &gateway-environment
+  VOCAGATEWAY_TOKEN_FILE: /run/secrets/vocagateway_token
+  VOCAGATEWAY_DEBUG: ${VOCAGATEWAY_DEBUG:-false}
+  # Blank means "not set": the gateway ignores an empty override and falls back
+  # to auto-discovery. On the default bridge network discovery only ever sees
+  # the container's private bridge IP, so this is how a phone-reachable address
+  # gets into the pairing QR without switching to host networking.
+  VOCAGATEWAY_PUBLIC_URL: ${VOCAGATEWAY_PUBLIC_URL:-}
+  VOCAGATEWAY_PAIRING_URL: ${VOCAGATEWAY_PAIRING_URL:-}
+  # Listener inside the container. Only worth changing under
+  # VOCAGATEWAY_NETWORK_MODE=host, where the container binds the host directly
+  # and the ports mapping below is discarded.
+  VOCAGATEWAY_BIND_HOST: ${VOCAGATEWAY_BIND_HOST:-0.0.0.0}
+  VOCAGATEWAY_PORT: ${VOCAGATEWAY_PORT:-8765}
+  VOCAGATEWAY_ENGINE: ${VOCAGATEWAY_ENGINE:-auto}
+  VOCAGATEWAY_RETENTION_HOURS: ${VOCAGATEWAY_RETENTION_HOURS:-24}
+  VOCAGATEWAY_DELETE_SUCCESSFUL_AUDIO: ${VOCAGATEWAY_DELETE_SUCCESSFUL_AUDIO:-true}
+
 services:
   gateway:
     image: ${VOCAGATEWAY_IMAGE:-vocaphone-gateway:local}
@@ -10,10 +31,8 @@ services:
     init: true
     network_mode: ${VOCAGATEWAY_NETWORK_MODE:-bridge}
     ports:
-      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:8765"
-    environment:
-      VOCAGATEWAY_TOKEN_FILE: /run/secrets/vocagateway_token
-      VOCAGATEWAY_DEBUG: ${VOCAGATEWAY_DEBUG:-false}
+      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:${VOCAGATEWAY_PORT:-8765}"
+    environment: *gateway-environment
     secrets:
       - vocagateway_token
     volumes:
@@ -31,10 +50,8 @@ services:
     init: true
     network_mode: ${VOCAGATEWAY_NETWORK_MODE:-bridge}
     ports:
-      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:8765"
-    environment:
-      VOCAGATEWAY_TOKEN_FILE: /run/secrets/vocagateway_token
-      VOCAGATEWAY_DEBUG: ${VOCAGATEWAY_DEBUG:-false}
+      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:${VOCAGATEWAY_PORT:-8765}"
+    environment: *gateway-environment
     secrets: [vocagateway_token]
     volumes: [vocagateway-data:/data]
 
@@ -48,10 +65,9 @@ services:
     init: true
     network_mode: ${VOCAGATEWAY_NETWORK_MODE:-bridge}
     ports:
-      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:8765"
+      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:${VOCAGATEWAY_PORT:-8765}"
     environment:
-      VOCAGATEWAY_TOKEN_FILE: /run/secrets/vocagateway_token
-      VOCAGATEWAY_DEBUG: ${VOCAGATEWAY_DEBUG:-false}
+      <<: *gateway-environment
       NVIDIA_VISIBLE_DEVICES: all
     gpus: all
     secrets: [vocagateway_token]
@@ -67,10 +83,8 @@ services:
     init: true
     network_mode: ${VOCAGATEWAY_NETWORK_MODE:-bridge}
     ports:
-      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:8765"
-    environment:
-      VOCAGATEWAY_TOKEN_FILE: /run/secrets/vocagateway_token
-      VOCAGATEWAY_DEBUG: ${VOCAGATEWAY_DEBUG:-false}
+      - "${VOCAGATEWAY_PUBLISH_HOST:-127.0.0.1}:${VOCAGATEWAY_PUBLISH_PORT:-8765}:${VOCAGATEWAY_PORT:-8765}"
+    environment: *gateway-environment
     devices:
       - /dev/dri:/dev/dri
     secrets: [vocagateway_token]

docs/deployment.md

@@ -131,16 +131,20 @@ The Compose project lives in this repository root:
 
 ```sh
 umask 077
-printf 'VOCAGATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env
-printf 'VOCAGATEWAY_PUBLISH_HOST=127.0.0.1\n' >> .env
-printf 'VOCAGATEWAY_PUBLISH_PORT=8765\n' >> .env
+cp .env.example .env
+printf 'VOCAGATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" >> .env
 docker compose up --detach --build
 ```
 
-[`.env.example`](../.env.example) is the annotated template for
-the same file, covering the optional image tag, network mode and Swagger UI
-settings. Copy it and append a generated token rather than committing either
-file.
+[`.env.example`](../.env.example) is the annotated template for the same file.
+It ships the loopback publication defaults uncommented and everything else
+commented out with an explanation: the pairing-QR address, the container
+listener, the engine choice, session retention, the optional image tag, network
+mode, and the Swagger UI. Start from it rather than writing `.env` by hand, so
+the options are in front of you. Never commit either file.
+
+The appended token overrides the empty `VOCAGATEWAY_TOKEN=` placeholder in the
+template; Compose uses the last assignment when a key repeats in `.env`.
 
 `VOCAGATEWAY_PUBLISH_HOST=127.0.0.1` is the safe default for Tailscale Serve. Set
 it to `0.0.0.0` only when direct LAN access is intentional and protected by the
@@ -228,7 +232,7 @@ Build one tag for both supported Linux architectures from the repository root:
 docker buildx build \
   --platform linux/amd64,linux/arm64 \
   --tag ghcr.io/your-user/vocaphone-gateway:latest \
-  --push server
+  --push .
 ```
 
 Set `VOCAGATEWAY_IMAGE` in `.env` to use that tag. Compose still includes a
@@ -260,9 +264,22 @@ VPN and never forward it from a router.
 With the default bridge network, the container only ever sees its own private
 bridge address (for example `172.19.0.2`), never the host's real Wi-Fi/Ethernet
 interface — so the pairing card's auto-discovered candidate list won't include
-a `192.168.x.x` address even after the change above. On Linux Docker Engine
-(not Docker Desktop on macOS/Windows), share the host's network namespace
-instead so discovery sees the real LAN IP directly:
+a `192.168.x.x` address even after the change above.
+
+The portable fix is to stop relying on discovery and name the address the phone
+should use:
+
+```dotenv
+VOCAGATEWAY_PUBLIC_URL=http://192.168.1.20:8765
+```
+
+The gateway puts that URL first in the pairing card and encodes it in the QR.
+It works on every Docker flavour, including Docker Desktop on macOS and
+Windows, and is the only option there. `VOCAGATEWAY_PAIRING_URL` is an accepted
+alias, checked second.
+
+On Linux Docker Engine (not Docker Desktop) you can instead share the host's
+network namespace so discovery sees the real LAN IP by itself:
 
 ```dotenv
 VOCAGATEWAY_NETWORK_MODE=host

docs/troubleshooting.md

@@ -152,7 +152,7 @@ deployment, also confirm Tailscale is connected and Serve is active. The
 recording should remain on the iPhone for Retry.
 
 For a container deployment, also check `docker compose ps` from `server/` and
-confirm the `vocaphone_vocaphone-data` volume is still mounted.
+confirm the `vocagateway_vocagateway-data` volume is still mounted.
 
 ## A LAN hostname such as homelabone does not connect
 
@@ -174,10 +174,13 @@ Keep the host firewall enabled. Do not use this LAN configuration to expose port
 If the pairing QR itself shows no LAN address to pick from (or only shows a
 `172.x`/bridge address), that's the same root cause: the container's default
 bridge network only exposes its own private interface to address
-auto-discovery, never the host's real LAN NIC. On Linux Docker Engine (not
-Docker Desktop), set `VOCAGATEWAY_NETWORK_MODE=host` in `.env` instead so
-the container shares the host's network namespace and discovery finds the
-`192.168.x.x` address directly. See [deployment.md](deployment.md#trusted-local-network).
+auto-discovery, never the host's real LAN NIC. Set
+`VOCAGATEWAY_PUBLIC_URL=http://192.168.1.20:8765` in `.env` to name the address
+the phone should use — this works on every Docker flavour, including Docker
+Desktop. On Linux Docker Engine only, `VOCAGATEWAY_NETWORK_MODE=host` is the
+alternative: the container shares the host's network namespace and discovery
+finds the `192.168.x.x` address directly. Recreate the service after either
+change. See [deployment.md](deployment.md#trusted-local-network).
 
 ## 401 unauthorized