From 626e7712f191de6612f6da6d7302fec0be6b4ede Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Fri, 18 Sep 2026 01:13:48 +0200
Subject: [PATCH] docs: add backend and web READMEs so each product has a setup
 path

---
 CONTRIBUTING.md             | 16 ++++++-----
 surfsense_backend/README.md | 54 +++++++++++++++++++++++++++++++++++++
 surfsense_web/README.md     | 48 +++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+), 7 deletions(-)
 create mode 100644 surfsense_backend/README.md
 create mode 100644 surfsense_web/README.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 307d9df61..84445c3dd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,14 +8,16 @@ Questions: [Discord](https://discord.gg/ejRNvftDp9) or [Discussions](https://git
 
 ## Getting set up
 
-This repo holds four products. You can clone all of it, then only run the tree you are changing — that is usually enough for a first PR.
+This repo holds four products. Clone it once, then open the README for the product you want to change. You do not need to run the other three.
 
-| Tree | Setup |
-|------|--------|
-| [`surfsense_local/`](surfsense_local/README.md) | Desktop app |
-| [`surfsense_mcp/`](surfsense_mcp/README.md) | MCP server (often the lightest first PR) |
-| `surfsense_backend/` | Scraper API / self-host backend |
-| `surfsense_web/` | Self-host web UI (`pnpm`, not npm) |
+| If you want to work on | Open |
+|------------------------|------|
+| Desktop app | [`surfsense_local/README.md`](surfsense_local/README.md) |
+| MCP server | [`surfsense_mcp/README.md`](surfsense_mcp/README.md) |
+| API / scrapers | [`surfsense_backend/README.md`](surfsense_backend/README.md) |
+| Self-host web UI | [`surfsense_web/README.md`](surfsense_web/README.md) |
+
+The web UI needs the API running. Desktop does not. MCP talks to any backend over HTTP.
 
 ```bash
 git clone https://github.com/<you>/SurfSense.git
diff --git a/surfsense_backend/README.md b/surfsense_backend/README.md
new file mode 100644
index 000000000..6b1439d82
--- /dev/null
+++ b/surfsense_backend/README.md
@@ -0,0 +1,54 @@
+# SurfSense backend
+
+FastAPI app: scraper API, knowledge base, auth, and the self-host server.
+
+This is not the desktop sidecar. Desktop Python lives in [`surfsense_local/backend/`](../surfsense_local/backend/).
+
+## You need
+
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/)
+- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector)
+- Redis (background jobs)
+
+The smallest way to get Postgres and Redis is from the repo root:
+
+```bash
+docker compose -f docker/docker-compose.deps-only.yml up -d db redis
+```
+
+## Run it
+
+```bash
+cp .env.example .env
+uv sync
+uv run alembic upgrade head
+uv run main.py --reload
+```
+
+API: http://localhost:8000  
+Docs: http://localhost:8000/docs
+
+`.env.example` is the config map. For local Docker Postgres the default `DATABASE_URL` already matches `deps-only`. Set `SECRET_KEY` to something of your own. Leave `SUNSET_MODE` unset.
+
+Uploads, connectors, and other background work need a worker in a second terminal:
+
+```bash
+uv run celery -A celery_worker.celery_app worker --loglevel=info --concurrency=1 --pool=solo --queues=surfsense,surfsense.connectors,surfsense.gateway
+```
+
+Scheduled jobs need beat as well (`uv run celery -A celery_worker.celery_app beat --loglevel=info`). Skip both until you touch that path.
+
+## Tests
+
+```bash
+uv run pytest -m unit
+AUTH_TYPE=LOCAL uv run pytest -m integration   # needs Postgres
+```
+
+More on the suite: [tests/README.md](tests/README.md).
+
+## UI
+
+The Next.js app is [`surfsense_web/`](../surfsense_web/README.md). It talks to this API. You do not need it for a backend-only change.
+
+Full stack, Google auth, ETL keys, and zero-cache: [manual installation](../surfsense_web/content/docs/manual-installation.mdx).
diff --git a/surfsense_web/README.md b/surfsense_web/README.md
new file mode 100644
index 000000000..5793e3956
--- /dev/null
+++ b/surfsense_web/README.md
@@ -0,0 +1,48 @@
+# SurfSense web
+
+Next.js UI for the self-host stack (App Router, `pnpm`).
+
+This is not the desktop UI. Desktop frontend lives in [`surfsense_local/frontend/`](../surfsense_local/frontend/).
+
+## You need
+
+- Node.js 20+ and [pnpm](https://pnpm.io/installation) (not npm)
+- The API in [`surfsense_backend/`](../surfsense_backend/README.md) on http://localhost:8000
+
+## Run it
+
+```bash
+cp .env.example .env
+```
+
+In `.env`, point at a backend on your machine (the example file uses Docker hostnames):
+
+```bash
+NEXT_PUBLIC_FASTAPI_BACKEND_URL=http://localhost:8000
+SURFSENSE_BACKEND_INTERNAL_URL=http://localhost:8000
+AUTH_TYPE=LOCAL
+ETL_SERVICE=DOCLING
+DEPLOYMENT_MODE=self-hosted
+```
+
+Then:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+App: http://localhost:3000
+
+Match `AUTH_TYPE` with the backend. Leave `SUNSET_MODE` unset.
+
+Live document/chat updates need [zero-cache](content/docs/manual-installation.mdx). Most UI PRs can run without it; the page just will not refresh itself.
+
+## Tests
+
+```bash
+pnpm test:unit
+pnpm format
+```
+
+Playwright needs Postgres, Redis, the API, and a worker. See [tests/README.md](tests/README.md).