diff --git a/.ddev/docker-compose.emdash.yaml b/.ddev/docker-compose.emdash.yaml
index c22d55e..a65d04e 100644
--- a/.ddev/docker-compose.emdash.yaml
+++ b/.ddev/docker-compose.emdash.yaml
@@ -11,8 +11,11 @@ services:
     restart: "no"
     expose:
       - "4321"
+    # Optional so a fresh clone boots without manual prep. Contributors
+    # who need overrides can `cp app/.env.example app/.env` and edit.
     env_file:
-      - ../app/.env
+      - path: ../app/.env
+        required: false
     environment:
       HOST: "0.0.0.0"
       PORT: "4321"
diff --git a/app/.env.example b/app/.env.example
new file mode 100644
index 0000000..567d465
--- /dev/null
+++ b/app/.env.example
@@ -0,0 +1,12 @@
+# Local-dev environment variables for the emdash dev container.
+# Copy this file to `app/.env` and edit if you need to override defaults.
+# Loaded by .ddev/docker-compose.emdash.yaml (env_file, required: false) —
+# everything here is optional; the dev server boots fine with no overrides.
+
+# Override where emdash stores data.db and uploads/ on disk.
+# Defaults to the working directory (which is /app inside the container).
+# STATE_DIR=/app/state
+
+# Astro / emdash:
+# HOST, PORT, NODE_ENV, EMDASH_ALLOWED_ORIGINS, EMDASH_SITE_URL are set in
+# the compose `environment:` block — set them here only to override.