From 791ad23bf5a4bef088d463cced16a133a0f708fa Mon Sep 17 00:00:00 2001
From: dndrade <68204412+dndrade@users.noreply.github.com>
Date: Mon, 13 Jul 2026 15:10:39 -0400
Subject: [PATCH 1/2] docker-compose example + readme update

---
 docs/README.md          | 29 +++++++++++++++++++++++++++++
 docs/docker-compose.yml | 19 +++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/docker-compose.yml

diff --git a/docs/README.md b/docs/README.md
index 730e2ba..2c1b0cc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -37,3 +37,32 @@ Cursor / Claude Code and let it do it:
 
 That's all the instrumentation there is. Everything else, funnels, retention, paths, the
 "what to fix" verdict, you just ask for.
+
+# Docker Compose
+
+Alternativelly, you may use `docker-compose.yml` to run the container.
+
+1. Place the compose file from this repo into the destination folder
+
+```sh
+~/smolanalytics/docker-compose.yml
+```
+
+2. Add your key and password values
+
+```yaml
+environment:
+      - SMOLANALYTICS_WRITE_KEY="your_key_here"
+      - SMOLANALYTICS_PASSWORD="your_password_here"
+```
+
+if using `.env`:
+```txt
+SMOLANALYTICS_WRITE_KEY="your_key_here"
+SMOLANALYTICS_PASSWORD="your_password_here"
+```
+
+3. Deploy the container
+```sh
+docker compose up -d
+```
\ No newline at end of file
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
new file mode 100644
index 0000000..49e1b9b
--- /dev/null
+++ b/docs/docker-compose.yml
@@ -0,0 +1,19 @@
+services:
+  smolanalytics:
+    image: ghcr.io/arjun0606/smolanalytics:latest
+    container_name: smolanalytics
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+
+    environment:
+      - SMOLANALYTICS_WRITE_KEY=${SMOLANALYTICS_WRITE_KEY}
+      - SMOLANALYTICS_PASSWORD=${SMOLANALYTICS_PASSWORD}
+
+    # .env can be also used if secrets 
+    # won't be written directly in the compose file
+    # env_file:
+    #   - .env
+    volumes:
+      - ./data:/data
+      

From ee20f5e048bb7001254c592bd330af1ce2b5e182 Mon Sep 17 00:00:00 2001
From: dndrade <68204412+dndrade@users.noreply.github.com>
Date: Tue, 14 Jul 2026 12:12:53 -0400
Subject: [PATCH 2/2] [docs] docker-compose example with persistent volume

---
 docs/README.md          | 73 ++++++++++++++++++++++++-----------------
 docs/docker-compose.yml | 29 ++++++++++------
 2 files changed, 62 insertions(+), 40 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 2c1b0cc..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,33 +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.
-
-# Docker Compose
-
-Alternativelly, you may use `docker-compose.yml` to run the container.
-
-1. Place the compose file from this repo into the destination folder
-
-```sh
-~/smolanalytics/docker-compose.yml
-```
-
-2. Add your key and password values
-
-```yaml
-environment:
-      - SMOLANALYTICS_WRITE_KEY="your_key_here"
-      - SMOLANALYTICS_PASSWORD="your_password_here"
-```
-
-if using `.env`:
-```txt
-SMOLANALYTICS_WRITE_KEY="your_key_here"
-SMOLANALYTICS_PASSWORD="your_password_here"
-```
-
-3. Deploy the container
-```sh
-docker compose up -d
-```
\ No newline at end of file
+"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
index 49e1b9b..96c9bee 100644
--- a/docs/docker-compose.yml
+++ b/docs/docker-compose.yml
@@ -1,19 +1,28 @@
 services:
   smolanalytics:
-    image: ghcr.io/arjun0606/smolanalytics:latest
-    container_name: smolanalytics
-    restart: unless-stopped
+    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_WRITE_KEY=${SMOLANALYTICS_WRITE_KEY}
-      - SMOLANALYTICS_PASSWORD=${SMOLANALYTICS_PASSWORD}
+      SMOLANALYTICS_PASSWORD: change-me
+      SMOLANALYTICS_WRITE_KEY: change-me
 
-    # .env can be also used if secrets 
-    # won't be written directly in the compose file
+    # ------------------------------------------------------------------
+    # 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
-    volumes:
-      - ./data:/data
-