Status: decision record — 2026-10-04. Complements README.md (how to build
today) and UPGRADE.md (how to move to a new upstream version).
Distribute the subpath build as a Docker image, produced from a fork of
open-webui/open-webui. For SimpleAudit Studio we currently do not even need
to publish the fork: build.sh in this directory rebuilds the identical image
from the upstream repo + this directory's patch, so the consumer side is
complete as-is. The fork is the vehicle for publishing (CI → ghcr.io) and
for making the upgrade loop one push instead of a local command.
Channel ranking:
- Docker image (
ghcr.io/sushantgautam/open-webui:vX.Y.Z-chat) — primary. Matches how Studio consumes OWUI (docker-compose.ymlimage) and how upstream itself ships (itsdocker.yamlworkflow). pip install— secondary, and only if it is fixed (see below). Not a viable channel today.- Repo of prebuilt script bundles — rejected (see below).
svelte.config.js and vite.config.ts read process.env.WEBUI_SUBPATH and
freeze it into the emitted JS (base: '/chat', relative: false);
src/lib/constants.ts bakes WEBUI_BASE_URL = base into every API/asset URL.
Consequence: one built artifact = one subpath. A /chat bundle cannot be
served at another prefix without rebuilding. This is fine (Studio always uses
/chat), but it rules out "ship one universal bundle".
pyproject.toml line 208:
force-include = { "CHANGELOG.md" = "open_webui/CHANGELOG.md", build = "open_webui/frontend" }but .github/workflows/release-pypi.yml never runs npm run build before
python -m build . — there is no build/ directory to force-include, so the
upstream open-webui wheel on PyPI is API-only. backend/open_webui/main.py:3027
then logs Frontend build directory not found ... Serving API only.
So "install from my repo with pip install" is not currently a real channel
for anyone, upstream included. It only becomes real if a release workflow does:
npm ci && WEBUI_SUBPATH=/chat npm run build # creates ./build with /chat baked in
python -m build . # wheel now bakes ./build → open_webui/frontend
If we ever ship this: the PyPI project must be renamed (e.g. open-webui-subpath)
because open-webui is taken, and every version needs a fresh npm build.
Option A (commit the built *.js bundles + patch + notes to a repo, rebuild by
asking an agent) is strictly worse than a fork:
- The minified bundle is the only source of truth — no clean base to rebuild
from when a new upstream version lands. The agent must produce a full frontend
build anyway, which means checking out upstream source, applying the patch,
and running
npm run build— i.e. it is already rebuilding a fork, just without the git scaffolding that makes that reproducible. - Bundles in git are 100s of KB of unmaintainable churn; a patch is reviewable.
git apply --checkgives a hard, machine-verifiable "does this patch still fit upstream?" gate. A repo of blobs has no such signal.
github.com/sushantgautam/open-webui ← fork of open-webui/open-webui
│ main: upstream v0.11.4 (8bd8b4fac) + the subpath commits
│ dev: pristine upstream v0.11.4 (kept clean as the re-align target)
│
├── subpath support (merge commit 42ac2ae70) ← the 121-file feature PORTED to
│ v0.11.4 (123 files, +1017/−305); merge-both resolution, E2E-verified
├── docker: node heap 6GB (c1674863c) ← NODE_OPTIONS=--max-old-space-size=6144
├── docs: FORK.md (f3755b1b1) ← fork purpose + build/publish/upgrade
├── ci: publish to sushantgautam (217f36f36) ← IMAGE_REPOSITORY → sushantgautam/open-webui
│
├── .github/workflows/docker.yaml ← upstream's, with:
│ IMAGE_REPOSITORY → sushantgautam/open-webui
│ webui_subpath dispatch input → `-subpath` tag
│ suffix (root tags stay clean)
│
├── .github/workflows/release-pypi.yml ← OPTIONAL. If kept: add
│ `npm ci && WEBUI_SUBPATH=/chat npm run build`
│ before `python -m build`; rename project
│ to open-webui-subpath. Otherwise delete.
│
├── .github/workflows/catch-up.yml ← manual trigger: see UPGRADE.md for the
│ exact steps; the workflow automates
│ fetch upstream tag → rebase →
│ apply --check → build → smoke → tag
└── README.md ← "what is this fork, how it differs,
how to rebuild at a new version"
Consumer side (already done, in this directory):
build.sh— local build from upstream @ pinned SHA + patch (no fork needed)Caddyfile.subpath— one-origin proxy, no prefix stripdocker-compose.yml— pointOPEN_WEBUI_IMAGEatghcr.io/sushantgautam/...once the fork exists; until then at the locally builtsimpleaudit/open-webui-subpath:chat
The unit of work when upstream releases a new version:
1. git fetch upstream <new-tag> # in the fork
2. git rebase upstream/<new-tag> # replay the 2 patch commits
(or: fresh clone @ tag + git apply subpath.patch)
3. git apply --check subpath.patch # HARD GATE — CI fails immediately
if the patch no longer fits
4. WEBUI_SUBPATH=/chat npm run build # frontend compiles?
5. docker build + smoke: /chat/health 200,
SPA has 0 unprefixed root refs, WS /chat/ws/socket.io → 101,
one LLM round-trip
6. tag v<upstream-ver>-chat → CI pushes ghcr.io
7. Studio: bump OPEN_WEBUI_IMAGE, re-run studio smoke (SSO + chat)
Drift data point (now resolved): against v0.11.4 (8bd8b4f) the v0.9.6
patch applied cleanly to only 33/121 files, 88 with conflicts (8 of the 9
core files). Ported on 2026-10-04 as a git merge (not apply --3way,
which aborts atomically on files upstream deleted) — 79 files resolved
merge-both. Porting a minor version is real work (~1 agent-hour) — that's
why the loop must keep the
apply --check + smoke gate, and why we pin and upgrade deliberately rather
than tracking main.
Publish the fork?→ Done (2026-10-04):sushantgautam/open-webuimain= v0.11.4 + subpath,dev= pristine v0.11.4; CI publishes root images on push, subpath onwebui_subpathdispatch.- If pip channel is ever wanted:
open-webui-subpathproject name; who maintains PyPI token/Trusted Publisher. - Tag suffix convention settled on
-subpath(matches the fork's CI input).