[AnishSarkar22]

What

Updates the Docker proposal and GPU images with the decisions made before building steps 4 to 14. Docs only; no code changes.

Layout: one core, two entries (ADR 0072)

• surfsense_local/ becomes a shared core (backend/, frontend/, sidecars/, runtimes/) with two entries: electron/ for the desktop and headless/ for the container.
• The supervisor (electron/src/main/sidecars/, net.ts, the session log) moves to sidecars/. A test fails on any electron import there.
• The staging scripts move from electron/scripts/ to runtimes/, which gains a target and a variant. With neither, it stages the desktop's build as today, so installers don't change.
• The image's files live in docker/surfsense/ (one folder per image, like docker/keygen/), built from the repo root.
• Step 4 is now this move plus the headless entry, in one PR, gated on a release-local.yml dry run.

The headless entry

• Builds the boot context from the environment and settles the secret before any Python process starts.
• Sets HF_HUB_OFFLINE, SURFSENSE_LOCAL_RUNTIME=docker and HOME=/data/home.
• Turns previews off and handles signals: the API exiting stops the container.
• A SURFSENSE_LOCAL_SIGNED_REGISTRY switch makes the venv backend read the signed plugin registry.

Releases

• Same VERSION and vX.Y.Z tag as the desktop.
• The tag push builds, smoke-tests and pushes X.Y.Z.
• latest moves only when the GitHub release is published, as a retag, so the desktop and the image go live together.
• Pre-releases never move latest.

GPU (ADR 0073, which supersedes ADR 0035's CUDA variant names)

• One CUDA variant, -cuda (CUDA 12.8, amd64). -cuda13 follows with arm64, and -cuda126 is dropped: it existed for GPU torch, which the new stack doesn't use.
• Each runtime has one source shared with the desktop:
  • llama.cpp comes from upstream's releases at the desktop's pin;
  • sd.cpp comes from the desktop's recipe with cpu and cuda variants;
  • audio.cpp is the desktop's own CPU build.
• Driver floor: 570.26 on Linux and 570.65 on Windows. It is kept beside the pin and enforced by the installer, NVIDIA_REQUIRE_CUDA and the no-GPU check.
• The installer detects the GPU, or users pick the variant by hand.

Networking, Caddy and sign-ins

• One container, every sidecar on loopback. Caddy is the only listener, and HTTPS is required for access from another machine.
• Claude subscriptions: the user installs Claude Code in the container, and the Claude dialog shows the container's commands.
• OAuth follows one rule: the callback lands on the browser's own origin. Plugins, Notion included, try a CIMD client, then DCR, then the user's own app, then paste-back. ChatGPT follows the rule as far as OpenAI's client allows.

The legacy-split proposal's Docker references follow the new folder and workflow names.

Why

The proposal was written before the legacy split, before opencode and the third worker, and before any GPU detail was checked against upstream. Building from it as it stood would have hit a Vulkan-only staging script, the wrong build context, an unsigned plugin registry and sign-ins that can't reach a container. The proposal now matches the code, and the open questions are closed or listed under "To verify while building".

Fixes # (none; updates the proposal tracked in #2100)

How to test

• python scripts/check_docs.py reports 0 problems.
• Read the Docker proposal, especially "One core, two entries", "The headless entry", "Releases" and "Sign-ins", plus gpu.md and ADRs 0072 and 0073.

Step 4 builds on the headless-entry patch on #2104; I'll coordinate with its assignee there before moving any code.

🤖 Generated with Claude Code

High-level PR Summary

This PR updates the Docker and GPU documentation to reflect architectural decisions made before implementation. It establishes a one core, two entries architecture where surfsense_local/ becomes a shared core with electron/ for desktop and headless/ for containers, moves the supervisor and staging scripts out of electron/ into shared folders, consolidates to a single CUDA 12.8 variant (-cuda) sourcing runtimes from upstream builds, and documents the sign-in flows, networking model, and release strategy where the Docker image ships alongside the desktop with synchronized versioning.

⏱️ Estimated Review Time: 15-30 minutes

💡 Review Order Suggestion

Order	File Path
1	docs/adr/0072-the-desktop-and-the-container-are-two-entries-over-one-core.md
2	docs/adr/0073-the-docker-gpu-image-is-one-cuda-12-8-variant-from-upstream-builds.md
3	docs/proposals/docker/README.md
4	docs/proposals/docker/gpu.md
5	docs/adr/0035-docker-compose-runs-the-desktop-stack.md
6	docs/adr/README.md
7	docs/proposals/legacy-split/README.md

[vercel]

@AnishSarkar22 is attempting to deploy a commit to the Rohan Verma's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}