diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..2bc8a2a
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,79 @@
+# Flatpak-Mirror (Test-Setup mit Docker Compose)
+
+Kuratiertes Flatpak-Repo: spiegelt nur die in `config/apps.yaml` freigegebenen
+Apps von Flathub und stellt sie über nginx bereit. Kein flat-manager nötig.
+
+## Schnellstart (lokale apps.yaml, ohne Git)
+
+```bash
+docker compose up -d --build
+```
+
+- `sync`-Container klont/pullt nichts von Git (solange `GIT_REPO_URL` leer ist),
+  sondern liest direkt `config/apps.yaml` (read-only gemountet).
+- Beim ersten Lauf: OSTree-Repo wird angelegt, Flathub-Remote eingerichtet,
+  die drei Beispiel-Apps werden gepullt. Das kann je nach App-Größe einige
+  Minuten dauern (Firefox, LibreOffice sind groß).
+- Logs verfolgen: `docker compose logs -f sync`
+- Repo ist danach erreichbar unter `http://localhost:8080`
+
+## Mit Git-Repo für die apps.yaml
+
+1. `.env.example` nach `.env` kopieren:
+   ```bash
+   cp .env.example .env
+   ```
+2. In `.env` mindestens `GIT_REPO_URL` setzen (öffentliches Repo reicht das
+   schon aus). `GIT_BRANCH` bei Bedarf anpassen (Standard: `main`).
+3. **Nur bei privaten Repos:** zusätzlich `GIT_USERNAME` und `GIT_TOKEN`
+   setzen. Als `GIT_TOKEN` ein Personal Access Token verwenden (nicht das
+   echte Account-Passwort!) – erzeugbar unter den Account-Einstellungen von
+   Gitea/GitHub/GitLab, idealerweise mit nur Lese-Rechten auf das eine Repo.
+
+`.env` wird per `.gitignore` von Git ignoriert – nie versehentlich committen.
+Das Repo braucht im Root eine `apps.yaml` mit der gleichen Struktur wie in
+`config/apps.yaml`. Der `./config`-Mount kann dann entfernt werden (oder
+bleibt einfach ungenutzt, `GIT_REPO_URL` hat Vorrang).
+
+**Sicherheitshinweis zum Token:** Es wird nie in die Git-URL eingebettet
+(`https://user:token@host/...`), da URLs in Logs auftauchen können. Stattdessen
+übergibt `sync.sh` das Token über `GIT_CONFIG_*`-Umgebungsvariablen an git,
+sodass es auch nicht als Kommandozeilenargument sichtbar ist (z. B. über
+`ps aux` auf dem Docker-Host). Es steht dennoch im Container-Environment und
+in `.env` im Klartext – Zugriff auf den Docker-Host und die `.env`-Datei
+entsprechend absichern (Dateiberechtigungen, kein Checkout in ein öffentlich
+lesbares Verzeichnis).
+
+## Client testen
+
+Auf einer Test-Maschine mit Flatpak installiert:
+
+```bash
+flatpak remote-add --no-gpg-verify test-repo http://<server-ip>:8080
+flatpak install test-repo org.mozilla.firefox
+```
+
+`--no-gpg-verify` ist nur für den lokalen Test ok — die Original-Signaturen
+von Flathub werden zwar mitkopiert, aber ohne den Flathub-Key im Client ist
+Verifizierung sonst nicht möglich. Für den Produktivbetrieb solltest du
+`ostree remote add` bzw. `flatpak remote-add` mit dem echten Flathub-GPG-Key
+konfigurieren, statt `--no-gpg-verify` zu verwenden.
+
+## Apps hinzufügen/entfernen
+
+Einfach `config/apps.yaml` (oder die Datei im Git-Repo) bearbeiten. Der
+Sync-Container prüft alle `SYNC_INTERVAL_SECONDS` (Standard: 900 = 15 Min.)
+erneut und pullt neue Einträge bzw. löscht entfernte Refs automatisch.
+
+Für einen sofortigen Testlauf, statt zu warten:
+
+```bash
+docker compose restart sync
+```
+
+## Nächste Schritte für den Produktivbetrieb
+
+- Sync über Webhook statt reinem Interval-Polling triggern
+- Shared Volume durch echtes Kubernetes-PVC (ReadWriteMany) oder S3 ersetzen
+- Monitoring/Alerting auf Sync-Fehler
+- Bei Bedarf später flat-manager vor dieses Repo setzen (siehe Chat-Verlauf)
\ No newline at end of file