From cd2a663935e344f8d22402b77c66913126bf2dc2 Mon Sep 17 00:00:00 2001
From: Oleks <oleks.kuksenko@gmail.com>
Date: Wed, 20 May 2026 14:00:37 +0300
Subject: [PATCH] ddev bootstrap: make app/.env optional, add .env.example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fresh clones errored out on `ddev start` because the compose file's
env_file: pointed at app/.env (gitignored). No env vars are actually
required by the code — STATE_DIR is the only one and has a default.

- Switch env_file to the path:+required:false form (Docker Compose
  2.24+; bundled with DDEV) so missing app/.env is non-fatal.
- Commit app/.env.example as documentation for contributors who do
  need overrides.
---
 .ddev/docker-compose.emdash.yaml |  5 ++++-
 app/.env.example                 | 12 ++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 app/.env.example

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.