mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-11-16 13:10:29 +00:00
The desktop app's stack, without Electron, ships as one container in docker/local/: a supervisor shared with Electron runs the API, the workers and the model servers on loopback, and Caddy is the only listener. Without a password it answers only localhost; with one it uses basic auth, over HTTPS when a domain is set. Images come as CPU, -cuda (12.8) and -cuda126 (12.6) on amd64 and arm64. The license is the desktop's offline file. The legacy stack in docker/ is not changed. ADR 0035 records the decision and supersedes parts of ADR 0004 (Docker out of scope, the loopback rule) and ADR 0012 (no CUDA), for Docker only.
2.9 KiB
2.9 KiB
ADR 0035: The desktop app's stack also ships as one Docker container, with Caddy as its only listener
- Status: Accepted
- Date: 2026-10-01
- Supersedes: ADR 0004 in part: Docker Compose leaves its out-of-scope list, and its loopback rule is narrowed to the API. ADR 0012 in part: Docker images may carry CUDA.
- Source: Docker proposal, GPU images
Context
The legacy self-host stack is surfsense_backend and surfsense_web with Postgres, Redis, Zero, SearxNG and OpenSandbox, built by docker-build.yml. Product direction is the desktop app, and self-hosters need a way to run it on a server, which ADR 0004 ruled out. ADR 0004 also kept the API on 127.0.0.1 because nothing authenticates a request, and binding it wider would make connection URLs an SSRF boundary.
Decision
surfsense_localships as a Docker image and a Compose file, beside the desktop app. It is the same tree and the same code, not a fork.- One container per install. A supervisor shared with Electron runs the API, the workers and the model servers, all on
127.0.0.1, over one/datavolume. - Caddy, in the same container, is the only listener. It serves the frontend, proxies the API under
/api, and refuses/internal/*. - With no password set, Caddy answers only requests addressed to
localhost,127.0.0.1or[::1]. WithSURFSENSE_PASSWORDset, it answers the configured hosts behind basic auth, over HTTPS when a domain is set. - Still one user per install: no accounts, as ADR 0004 says.
- The license is the same offline Keygen file as the desktop app (ADR 0019).
- Images come in a CPU variant and CUDA variants named as the legacy backend's are (
-cuda,-cuda126). The desktop app stays Vulkan-only. - Studio's model-written code runs in the worker as on the desktop (ADR 0028); the container is the only boundary added.
Consequences
- ADR 0004's other choices stand: SQLite, Huey, no accounts, no multi-seat LAN. One container is what keeps them true, since the database, the queue, the event broker and
/internal/eventsall assume one machine. - The API still never binds beyond loopback, in any mode.
- The legacy self-host compose can be retired once the new one ships. The license and scraper API backend in
surfsense_backendis not part of this and stays. - Nothing hosted is removed before the purge on 18 Oct 2026.
- A CUDA image is several GB larger than the CPU one, and its builds compile sd.cpp, and llama.cpp where upstream ships no binary.
- A fork can strip the license check, as it can on the desktop; enforcement stays server-side at the scraper API.
Where the code stands
Nothing is built. The proposal's steps are the work.