diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f58db20
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,16 @@
+# Lightning Git local Docker stack. Copy this file to .env and fill it in.
+# docker compose reads it; do not wrap values in quotes.
+
+# Supabase project, free tier is enough (Project Settings -> API).
+# SUPABASE_API_KEY is the service_role key: the backend is a trusted server and
+# needs it to write metadata. SUPABASE_ANON_KEY is the public anon key.
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_API_KEY=your-service-role-key
+SUPABASE_ANON_KEY=your-anon-key
+
+# GitHub OAuth app, only needed to add repositories (the backend clones them on
+# your behalf). Leave these as placeholders to boot the stack and sign in; set
+# real values when you want to watch a repo.
+GITHUB_CLIENT_ID=placeholder
+GITHUB_CLIENT_SECRET=placeholder
+GITHUB_CALLBACK_URL=http://localhost:8080/auth/github/callback
diff --git a/.gitignore b/.gitignore
index eea2b45..4619c70 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,6 @@
 *.log
 .idea/
 *.swp
+
+# local Docker stack secrets (see .env.example)
+/.env
diff --git a/README.md b/README.md
index 5b2399f..fdb311d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/banner.png" alt="lightning-git: catch Git conflicts before they reach a pull request" width="100%">
+</p>
+
 # Lightning Git
 
 ![alpha](https://img.shields.io/badge/status-alpha-9b2c2c?style=flat-square) ![CI](https://img.shields.io/badge/CI-path--filtered-1a1a1a?style=flat-square) ![tests](https://img.shields.io/badge/tests-passing-2d6a4f?style=flat-square) ![self-hosted](https://img.shields.io/badge/self--hosted-9b2c2c?style=flat-square)
@@ -76,6 +80,22 @@ The Notbremse (the German term for an emergency brake, kept as a product name) i
 
 Each package keeps its own lockfile and builds on its own. There is no root workspace and no shared `node_modules`. A deploy host points at a single subfolder and never has to understand the rest of the repo, and the VS Code extension is packaged without the dependency-hoisting surprises a shared install would cause. The cost is that the two Node packages install separately; for three pieces that ship to different places, that is the cheaper trade.
 
+## Quickstart with Docker
+
+The backend and the frontend run together with one command. You need Docker and a Supabase project; the free tier is enough, and the backend uses it for accounts and project metadata.
+
+```bash
+cp .env.example .env
+# put your Supabase URL and keys in .env
+docker compose up --build
+```
+
+The frontend is then on http://localhost:5173 and the backend on http://localhost:8080.
+
+First-time setup also needs the database schema once: run `backend/src/supabase/table_creation.sql` in your Supabase project's SQL editor. Adding a repository to watch uses GitHub authorization so the backend can clone it read-only. Set the `GITHUB_*` values in `.env` for that; sign-up and sign-in work without them.
+
+This stack runs Lightning Git locally. Production deploys each package from its own subfolder; see [DEPLOYMENT.md](DEPLOYMENT.md).
+
 ## Running it locally
 
 Each package has its own README with the real detail. In short:
diff --git a/assets/banner.png b/assets/banner.png
new file mode 100644
index 0000000..2198d1e
Binary files /dev/null and b/assets/banner.png differ
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..563d078
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,20 @@
+# Local development stack: the backend and the frontend with one command.
+# Requires Docker and a Supabase project. Copy .env.example to .env and fill it
+# in first. This runs Lightning Git locally; production deploys each package from
+# its own subfolder (see DEPLOYMENT.md).
+services:
+  backend:
+    build: ./backend
+    env_file: .env
+    ports:
+      - "8080:8080"
+
+  frontend:
+    build: ./frontend
+    environment:
+      VITE_API_BASE_URL: "http://localhost:8080"
+      VITE_WS_URL: "ws://localhost:8080"
+    ports:
+      - "5173:5173"
+    depends_on:
+      - backend
diff --git a/frontend/.dockerignore b/frontend/.dockerignore
new file mode 100644
index 0000000..69e11c9
--- /dev/null
+++ b/frontend/.dockerignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+.env
+.env.*
diff --git a/frontend/Dockerfile b/frontend/Dockerfile
new file mode 100644
index 0000000..0899323
--- /dev/null
+++ b/frontend/Dockerfile
@@ -0,0 +1,9 @@
+# Frontend dev server for the local Docker stack (see ../docker-compose.yml).
+# Production builds the static site instead; see ../DEPLOYMENT.md.
+FROM node:20-slim
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+EXPOSE 5173
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]