feat(docker): local models, a password set up on first visit, and HTTPS in the image

.github/workflows/docker-tests.yml

@@ -1,6 +1,6 @@
 name: Docker Tests
 
-# The Docker entry and ghcr.io/modsetter/surfsense (docs/proposals/docker/README.md),
+# The Docker entry and ghcr.io/modsetter/surfsense (docs/architecture/docker.md),
 # tested without pushing an image; release-docker.yml publishes. dev pushes write
 # only the build cache. The shared core's own
 # tests are Desktop Tests'; here only what the entry and the image add.
@@ -36,6 +36,7 @@ jobs:
       frontend: ${{ steps.filter.outputs.frontend || 'true' }}
       image: ${{ steps.filter.outputs.image || 'true' }}
       backend: ${{ steps.filter.outputs.backend || 'true' }}
+      installer: ${{ steps.filter.outputs.installer || 'true' }}
     steps:
       - uses: actions/checkout@v7
         with:
@@ -57,10 +58,8 @@ jobs:
               - 'docker/surfsense/**'
               - 'surfsense_local/headless/**'
               - 'surfsense_local/sidecars/**'
-              # opencode's staging, and what it imports.
-              - 'surfsense_local/runtimes/opencode/**'
-              - 'surfsense_local/runtimes/pinned-download.mjs'
-              - 'surfsense_local/runtimes/windows-locks/**'
+              # The image stages llama.cpp, sd.cpp, audio.cpp and opencode with these.
+              - 'surfsense_local/runtimes/**'
               - 'surfsense_local/backend/pyproject.toml'
               - 'surfsense_local/backend/uv.lock'
               # The bundled models' downloads, which the build runs.
@@ -81,6 +80,12 @@ jobs:
               - 'surfsense_local/backend/scripts/fetch_*.py'
               - 'backend/plugins/bundles/core/manifest/**'
               - '.github/workflows/docker-tests.yml'
+            installer:
+              - 'docker/scripts/**'
+              # The files the installers download.
+              - 'docker/surfsense/docker-compose.yml'
+              - 'docker/surfsense/.env.example'
+              - '.github/workflows/docker-tests.yml'
 
   headless:
     name: Headless
@@ -156,7 +161,9 @@ jobs:
           persist-credentials: false
 
       - name: Check the compose file
-        run: docker compose -f docker/surfsense/docker-compose.yml --env-file docker/surfsense/.env.example config -q
+        run: |
+          docker compose -f docker/surfsense/docker-compose.yml --env-file docker/surfsense/.env.example config -q
+          docker compose -f docker/surfsense/dev/compose.yml config -q
 
       - uses: docker/setup-buildx-action@v4
 
@@ -239,11 +246,32 @@ jobs:
             -v "$PWD/docs/contracts:/app/docs/contracts:ro" \
             surfsense:backend-tests
 
+  # The one-line installers against a stand-in docker; ubuntu-latest carries
+  # shellcheck and pwsh, so both scripts run.
+  installer:
+    name: Installers
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: changes
+    if: needs.changes.outputs.installer == 'true'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The token stays out of .git/config, where the code under test could read it.
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - name: Shellcheck
+        run: shellcheck docker/scripts/install.sh
+      - name: Run tests
+        run: node --test docker/scripts/install.test.ts
+
   gate:
     name: Docker Gate
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    needs: [changes, headless, frontend, image, backend]
+    needs: [changes, headless, frontend, image, backend, installer]
     if: always()
     steps:
       - name: Check every job

AGENTS.md

@@ -12,7 +12,7 @@ Desktop app plus SurfSense's own backend. Three trees:
 | `surfsense_local` | Electron desktop |
 | `backend` | The one SurfSense backend, one process run by `server/`: the [license portal](docs/architecture/license/portal.md) in `license/`, its `mailer/`, and `plugins/`, which holds SurfSense's own plugin servers ([plugin host](docs/architecture/plugin-host.md)) and the [registry](docs/architecture/plugin-registry.md); `plugins/bundles/` holds the earlier, local design's SDK and tooling, deferred |
 
-The hosted service closed on 18 Oct 2026, when its user data was purged. The self-hosted stack, `surfsense_backend`, `surfsense_web`, `surfsense_mcp` and `docker/`, lives only on the `legacy` branch ([legacy split](docs/proposals/legacy-split/README.md)). Product direction is local + API.
+The hosted service closed on 18 Oct 2026, when its user data was purged. The self-hosted stack, `surfsense_backend`, `surfsense_web`, `surfsense_mcp` and `docker/`, lives only on the `legacy` branch ([legacy stack](docs/architecture/legacy.md)). Product direction is local + API.
 
 ## Code organization
 
@@ -83,7 +83,8 @@ pre-commit run --all-files
 | Desktop | `cd surfsense_local/electron && pnpm test` |
 | Docker entry | `cd surfsense_local/headless && pnpm test` |
 | Frontend in Docker mode | `cd surfsense_local/frontend && pnpm test:docker` (tests tagged `docker`; `pnpm test` leaves them out) |
-| Docker image | `SURFSENSE_TEST_IMAGE=<image> node --test surfsense_local/headless/image.test.ts` (starts the image on port 4929) |
+| Docker installers | `node --test docker/scripts/install.test.ts` (both scripts against a stand-in `docker`; `install.ps1`'s half needs `pwsh`) |
+| Docker image | `SURFSENSE_TEST_IMAGE=<image> node --test surfsense_local/headless/image.test.ts` (starts the image on ports 4929 and 4943; `SURFSENSE_TEST_IMAGE_PORT=4931` moves them to 4931 and 4945, beside a running install) |
 | Backend in the image | build `docker/surfsense/Dockerfile --target backend-tests` and run it with `tests/` and `docs/contracts/` mounted, as `docker-tests.yml` does; it runs `pytest -m image` |
 CI: `.github/workflows/`. New behavior: one failing test, then the minimum code to pass it. Use the `tdd` skill. Tests hit public seams, not internals.
 

README.ar.md

@@ -54,6 +54,14 @@ https://github.com/user-attachments/assets/073577b7-f055-4f59-8540-330bd764aeb0
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**استضفه بنفسك على خادم** باستخدام Docker، وافتحه من أي جهاز على شبكتك. شغّل الأمر نفسه مرة أخرى للتحديث.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+على Windows مع Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## بداية سريعة
 
 1. تثبيت SurfSense وإتمام الإعداد الأولي (Start setting up).

README.de.md

@@ -54,6 +54,14 @@ SurfSense ist eine kostenlose Open-Source-Desktop-App für Dokumente, die du nic
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Betreibe es selbst auf einem Server** mit Docker und öffne es von jedem Gerät in deinem Netzwerk. Führe denselben Befehl erneut aus, um es zu aktualisieren.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+Unter Windows mit Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Schnellstart
 
 1. Installiere SurfSense und durchlaufe beim ersten Start die Einrichtung.

README.es.md

@@ -55,6 +55,14 @@ SurfSense es una aplicación de escritorio gratuita y de código abierto para lo
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Alójalo en tu propio servidor** con Docker y ábrelo desde cualquier dispositivo de tu red. Ejecuta el mismo comando de nuevo para actualizarlo.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+En Windows con Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Inicio rápido
 
 1. Instala SurfSense y completa la configuración inicial.

README.fr.md

@@ -54,6 +54,14 @@ SurfSense est une application de bureau gratuite et open source pour les documen
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Hébergez-le vous-même sur un serveur** avec Docker, et ouvrez-le depuis n’importe quel appareil de votre réseau. Relancez la même commande pour le mettre à jour.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+Sous Windows avec Docker Desktop : `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Démarrage rapide
 
 1. Installez SurfSense et effectuez la configuration initiale.

README.hi.md

@@ -54,6 +54,14 @@ SurfSense एक मुफ़्त, ओपन-सोर्स डेस्क
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**इसे Docker के साथ अपने सर्वर पर खुद होस्ट करें**, और अपने नेटवर्क के किसी भी डिवाइस से खोलें। अपडेट करने के लिए वही कमांड फिर से चलाएं।
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+Docker Desktop वाले Windows पर: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## झटपट शुरुआत
 
 1. SurfSense इंस्टॉल करें और शुरुआती सेटअप पूरा करें।

README.ja.md

@@ -54,6 +54,14 @@ SurfSense は、アップロードできない文書のための、無料のオ
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Docker でサーバーにセルフホスト**し、ネットワーク上のどのデバイスからでも開けます。更新するには、同じコマンドをもう一度実行してください。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+Windows（Docker Desktop）の場合：`irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## クイックスタート
 
 1. SurfSense をインストールし、最初のセットアップを済ませます。

README.ko.md

@@ -54,6 +54,14 @@ SurfSense는 업로드할 수 없는 문서를 위한 무료 오픈소스 데스
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Docker로 서버에 직접 호스팅**하고, 네트워크의 어느 기기에서든 여세요. 업데이트하려면 같은 명령을 다시 실행하세요.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+Docker Desktop이 설치된 Windows에서: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## 빠른 시작
 
 1. SurfSense를 설치하고 초기 설정을 마칩니다.

README.md

@@ -62,6 +62,14 @@ SurfSense is a free, open-source desktop app for documents you can't upload. A p
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Self-host it on a server** with Docker, and open it from any device on your network. Run the same command again to update.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+On Windows with Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Quick start
 
 1. Install SurfSense and do the initial onboarding setup.

README.pt-BR.md

@@ -55,6 +55,14 @@ O SurfSense é um aplicativo de desktop gratuito e open source para os documento
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Hospede no seu próprio servidor** com Docker e abra de qualquer dispositivo da sua rede. Execute o mesmo comando de novo para atualizar.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+No Windows com Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Início rápido
 
 1. Instale o SurfSense e faça a configuração inicial.

README.ru.md

@@ -54,6 +54,14 @@ SurfSense — бесплатное настольное приложение с
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**Разверните на своём сервере** с Docker и открывайте с любого устройства в вашей сети. Чтобы обновить, запустите ту же команду ещё раз.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+В Windows с Docker Desktop: `irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## Быстрый старт
 
 1. Установите SurfSense и пройдите первоначальную настройку.

README.zh-CN.md

@@ -54,6 +54,14 @@ SurfSense 是一款免费开源的桌面应用，专为那些不能上传的文
 | **macOS** Apple Silicon | [SurfSense-arm64.dmg](https://www.surfsense.com/downloads/mac?src=readme) |
 | **Linux** x64 | [AppImage](https://www.surfsense.com/downloads/linux-appimage?src=readme) · [deb](https://www.surfsense.com/downloads/linux-deb?src=readme) |
 
+**用 Docker 在服务器上自托管**，并在你网络中的任何设备上打开。再次运行同一条命令即可更新。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
+```
+
+在装有 Docker Desktop 的 Windows 上：`irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex`
+
 ## 快速开始
 
 1. 安装 SurfSense，完成初始设置。