# 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.