diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..8bcda90
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,16 @@
+# Copier ce fichier en ".env" pour du dev local avec `docker compose` (le vrai ".env" est
+# gitignore, jamais committe). En production (Coolify), NE PAS utiliser ce fichier : definir ces
+# memes variables dans l'onglet "Environment Variables" de l'application Coolify.
+
+# --- Authentification HTTP Basic (UI + API) ---
+# Si absentes, l'authentification est desactivee (pratique en dev, jamais en prod).
+# Generer un hash pour un nouveau mot de passe :
+#   node -e "console.log(require('bcryptjs').hashSync('VOTRE_MOT_DE_PASSE', 10))"
+AUTH_USERNAME=nico
+AUTH_PASSWORD_HASH=
+
+# --- Parametres optionnels (defauts raisonnables si non definis, voir src/config.ts) ---
+# PORT=3000
+# MAX_UPLOAD_MB=2048
+# STATS_SAMPLE_CAP=50000
+# CC_TIMEOUT_MS=600000
diff --git a/README.md b/README.md
index bc89d71..be182c4 100644
--- a/README.md
+++ b/README.md
@@ -56,12 +56,16 @@ AUTH_USERNAME=nico
 AUTH_PASSWORD_HASH=$2a$10$...   # sortie de la commande ci-dessus
 ```
 
-En local avec `docker compose`, un fichier `.env` (gitignore) a la racine du repo fonctionne aussi :
+En local avec `docker compose`, un fichier `.env` (gitignore, jamais committe) a la racine du repo
+fonctionne aussi — `docker compose` le charge automatiquement :
 
+```bash
+cp .env.example .env
+# puis editer .env avec un vrai AUTH_PASSWORD_HASH genere via la commande ci-dessus
 ```
-AUTH_USERNAME=nico
-AUTH_PASSWORD_HASH=$2a$10$...
-```
+
+[.env.example](.env.example) est committe et documente toutes les variables disponibles ; `.env`
+(vos vraies valeurs) ne l'est jamais.
 
 ## Deploiement Coolify