From e5ecb1e3135f55bc0cad6d71e908c23a7e73467d Mon Sep 17 00:00:00 2001
From: stroblme <stroblme@posteo.de>
Date: Thu, 15 Oct 2026 15:58:52 +0200
Subject: [PATCH] make dev and make up warn when .env lacks a key compose would
 default

Only keys .env.example lists, so optional ones such as APP_PORT stay quiet.
A missing TZ used to run every cron on UTC without a word. Never fails.
---
 Makefile                        | 13 ++++++++++++-
 docs/reference/configuration.md |  3 ++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 43058cd..be8cae8 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
 # Convenience targets for development, testing, linting, and deployment.
 # The workspace root delegates to these (see ../Makefile).
 
-.PHONY: init dev-utils dev dev-local dev-lan rebuild-frontend up down update install dev-backend dev-frontend \
+.PHONY: init env-check dev-utils dev dev-local dev-lan rebuild-frontend up down update install dev-backend dev-frontend \
         generate-client sync-example test test-backend test-checks test-frontend soak bench-startup lint lint-backend \
         lint-frontend format-frontend umami build docs docs-serve clean help
 
@@ -39,6 +39,17 @@ help:  ## Show available targets
 # `make dev DOMAIN=fluksio.com` still wins.
 dev dev-utils dev-local dev-lan rebuild-frontend: export DOMAIN ?= localhost
 
+# A key the template lists and the compose files default, missing from .env,
+# falls back without a word. For TZ that means every cron runs on UTC. Only a
+# warning, so a start never fails over it.
+dev dev-local dev-lan up: env-check
+env-check:
+	@missing=$$(grep -ohE '\$$\{[A-Z_]+:?-' docker/compose*.yml | sed 's/^..//; s/:\{0,1\}-$$//' | sort -u \
+	  | while read -r k; do \
+	      grep -q "^$$k=" .env.example && ! grep -q "^$$k=" .env && printf ' %s' "$$k"; \
+	    done); \
+	[ -z "$$missing" ] || echo "  ! .env lacks$$missing, so compose uses its defaults. See .env.example."
+
 # First-time bootstrap. Idempotent: only secrets still set to `changethis` are
 # generated, so an existing .env keeps its values.
 init:  ## First-time setup (.env + secrets + docker network)
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 1f44773..47957e8 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -121,7 +121,8 @@ stack does. Production disables it entirely. Staging and production also
 refuse `changethis` values for the session key or administrator password.
 
 Set `TZ` in `.env` for schedules that should follow local time, such as
-`Europe/Berlin`.
+`Europe/Berlin`. `make up` and `make dev` warn when `.env` lacks it, or any other
+key `.env.example` lists that Compose would otherwise default.
 
 ## Engine and resources