diff --git a/.env.example b/.env.example
index 59a4327..7163ef3 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,17 @@
+# Kopiere zu .env und trage deine Werte ein.
+# .env ist per .gitignore ausgenommen — Secrets landen nie im Repo.
+
+# Kochwas-App (nur relevant, wenn du die App lokal startest; die Compose-
+# Setups setzen ihre eigenen Pfade im Container).
 DATABASE_PATH=./data/kochwas.db
 IMAGE_DIR=./data/images
 SEARXNG_URL=http://localhost:8888
+
+# Brave Search API-Key (https://api-dashboard.search.brave.com/).
+# Leer lassen, wenn du ohne Brave testen willst — andere Engines laufen
+# trotzdem. Fehlt der Key, antwortet die Brave-Engine nur mit 401.
+BRAVE_API_KEY=
+
+# SearXNG-Secret: beliebig lange Zufallskette. Für Prod mit
+# `openssl rand -hex 32` generieren und in der Pi-.env ablegen.
+SEARXNG_SECRET=dev-secret-change-me
diff --git a/docker-compose.yml b/docker-compose.yml
index 1249842..a9b136a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,11 +1,47 @@
+# Dev-Setup: nur SearXNG läuft im Container; Kochwas selbst startest du
+# lokal mit `npm run dev`. SEARXNG_URL=http://localhost:8888 wird von der
+# App automatisch erkannt (oder via .env gesetzt).
+#
+# Starten:
+#   cp .env.example .env   # einmalig, Werte anpassen
+#   docker compose up -d
+#   npm run dev
+#
+# Der Init-Container expandiert ${BRAVE_API_KEY} und ${SEARXNG_SECRET} aus
+# der .env genau wie prod — damit testet man lokal mit dem gleichen Flow.
+
 services:
+  searxng-init:
+    image: searxng/searxng:latest
+    restart: 'no'
+    user: root
+    entrypoint:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        python3 -c "import os; open('/out/settings.yml','w').write(os.path.expandvars(open('/in/settings.yml').read()))"
+    volumes:
+      - ./searxng:/in:ro
+      - searxng-config:/out
+    environment:
+      - FORCE_OWNERSHIP=false
+      - BRAVE_API_KEY=${BRAVE_API_KEY:-}
+      - SEARXNG_SECRET=${SEARXNG_SECRET:-dev-secret-change-me}
+
   searxng:
     image: searxng/searxng:latest
     ports:
       - '8888:8080'
     volumes:
-      - ./searxng:/etc/searxng
+      - searxng-config:/etc/searxng
     environment:
       - BASE_URL=http://localhost:8888/
       - INSTANCE_NAME=kochwas-search-dev
+    depends_on:
+      searxng-init:
+        condition: service_completed_successfully
     restart: unless-stopped
+
+volumes:
+  searxng-config: