owui-tools/docs/deployment/README.md

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.
4. Gitea, only if you want the VM sub-agent to publish. See ../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 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.