diff --git a/docs/README.md b/docs/README.md
index 730e2ba..3fae515 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,48 @@ docker run -p 8080:8080 -v $PWD/data:/data \
 # the image binds 0.0.0.0, so a dashboard password is required (echo the value to keep it).
 ```
 
+## Docker Compose
+
+For a setup that persists across restarts, use [`docs/docker-compose.yml`](docs/docker-compose.yml) instead of a bare `docker run`. It wires up the same image with a bind-mounted `./data` folder, so your event log survives `down`/`up`.
+
+**1. Grab the file**
+
+```sh
+curl -O https://raw.githubusercontent.com/Arjun0606/smolanalytics/main/docs/docker-compose.yml
+```
+
+**2. Set your secrets**
+
+Open it and set `SMOLANALYTICS_PASSWORD` and `SMOLANALYTICS_WRITE_KEY` (both required — `serve` refuses to run on a public bind without a password). Generate real values:
+
+```sh
+openssl rand -hex 12   # password
+openssl rand -hex 16   # write key
+```
+
+Two ways to set them, pick one:
+- **Inline (default):** edit the values directly under `environment:`.
+- **`.env` file:** comment out the `environment:` block, uncomment `env_file:`, and put the same two vars in a `.env` file next to the compose file.
+
+Only one should be active at a time — if both are uncommented, `environment:` silently wins and your `.env` file is ignored.
+
+**3. Run it**
+
+```sh
+docker compose up -d
+```
+
+`localhost:8080` is up, data lives in `./data`.
+
+**4. Confirm persistence**
+
+```sh
+docker compose down
+docker compose up -d
+```
+
+Your login and data are still there.
+
 ## Guides
 
 - [Next.js](nextjs.md)
@@ -36,4 +78,4 @@ Cursor / Claude Code and let it do it:
    and **`identify()`** on login so a user's events tie together.
 
 That's all the instrumentation there is. Everything else, funnels, retention, paths, the
-"what to fix" verdict, you just ask for.
+"what to fix" verdict, you just ask for.
\ No newline at end of file
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
new file mode 100644
index 0000000..96c9bee
--- /dev/null
+++ b/docs/docker-compose.yml
@@ -0,0 +1,28 @@
+services:
+  smolanalytics:
+    image: ghcr.io/arjun0606/smolanalytics
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data:/data
+    restart: unless-stopped
+
+    # ------------------------------------------------------------------
+    # OPTION A — inline env vars (default, active)
+    # required: SMOLANALYTICS_PASSWORD (serve refuses a public bind without it)
+    # required: SMOLANALYTICS_WRITE_KEY (event ingestion + MCP auth)
+    # ------------------------------------------------------------------
+    environment:
+      SMOLANALYTICS_PASSWORD: change-me
+      SMOLANALYTICS_WRITE_KEY: change-me
+
+    # ------------------------------------------------------------------
+    # OPTION B — .env file
+    # 1. Comment out the `environment:` block above.
+    # 2. Uncomment `env_file:` below.
+    # 3. Create a `.env` file next to this compose file:
+    #      SMOLANALYTICS_PASSWORD=change-me
+    #      SMOLANALYTICS_WRITE_KEY=change-me
+    # ------------------------------------------------------------------
+    # env_file:
+    #   - .env