Initial Commit

docs/deployment/README.md

@@ -0,0 +1,68 @@
+# The services outside this repo
+
+`docker-compose.yml` in the project root brings up everything the tools need *inside* the
+security boundary: the gateway, the guarded namespace, squid, SearXNG, valkey, the Octave
+sandbox, and the VM sub-agent's own containers. You do not need anything here for those.
+
+These three run outside it and have to exist first.
+
+| File | Service | Needed by | Optional? |
+|---|---|---|---|
+| `ollama.compose.yml` | Ollama | everything | No — this is the model |
+| `open-webui.compose.yml` | Open WebUI | everything | No — this is the front end |
+| `gitea.compose.yml` | Gitea | `vm_agent` only | Yes — without it a session still runs and keeps its files, it just returns no link |
+
+Each file is the working configuration from a real deployment with the secrets and domain
+names replaced. Read the header of each before running it; the parts that matter to
+owuitools are called out there, and in two places getting them wrong produces a failure
+that does not look like a configuration problem.
+
+## Project names are pinned, on purpose
+
+Each file sets its own `name:`. Compose otherwise derives a project name from the directory
+the file sits in, so running these as `docker compose -f docs/deployment/...` would produce
+a project called `deployment` and a network called `deployment_default`.
+
+That matters because the tool server joins Open WebUI's network **by name**, expecting
+`openwebui_default`. Without the pin, following the install guide in order fails at the next
+step with *"network declared as external, but could not be found"*. If you already run Open
+WebUI under a different project name, set `OWUITOOLS_OWUI_NETWORK` in
+`configs/owuitools.env` rather than renaming your stack.
+
+## Order
+
+1. **Ollama**, and pull your model. Everything else waits on it.
+2. **Open WebUI**, pointed at Ollama. Check you can chat before going further — if that
+   does not work, nothing downstream will, and the tool server's failures will be blamed
+   for it.
+3. **owuitools** itself: `cp configs/owuitools.env.example configs/owuitools.env`, generate
+   a token, `docker compose up -d --build`. See [../install-ubuntu-desktop.md](../install-ubuntu-desktop.md).
+4. **Gitea**, only if you want the VM sub-agent to publish. See [../setup/gitea.md](../setup/gitea.md).
+
+## The two settings that cause confusing failures
+
+**`ENABLE_FORWARD_USER_INFO_HEADERS: "True"`** on Open WebUI. Without it the tool server
+never learns which user or which chat a call belongs to. The per-user rate limit has
+nothing to key on, and the VM sub-agent's live view logs *"live progress disabled: no
+usable chat id was forwarded"* and shows nothing — which reads as a broken feature rather
+than a missing header.
+
+**`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER: "7200"`**. Unset does **not** mean unlimited: Open
+WebUI falls back to `AIOHTTP_CLIENT_TIMEOUT`, which defaults to 300 seconds. A `vm_agent`
+session runs for minutes to hours, so at the default it is cut off at five minutes — often
+with the work already done and only the reporting left. See
+[../advanced-params.md](../advanced-params.md) for the three clocks that have to agree.
+
+## Ollama is unauthenticated, and that shapes the design
+
+Ollama has no authentication at all and serves `DELETE /api/delete`, `POST /api/pull` and
+`POST /api/create`. Anything that can reach port 11434 can delete your model.
+
+Nothing in this project talks to it directly. The VM sub-agent — the component that runs a
+second model on behalf of whoever is chatting — reaches it through `owuitools-vmgw`, an
+nginx that exposes exactly `/ollama/api/chat` and `/ollama/api/ps` as *exact-match*
+locations and returns 404 for everything else. Its container can reach that one address and
+nothing else, enforced by a default-deny iptables policy in `vmguard/firewall.sh`.
+
+That is also why the compose file binds Ollama to the docker bridge address rather than
+`0.0.0.0`. If you change it, change it knowingly.