diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..954ba59
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,54 @@
+# Copier en .env (ignoré par Git) puis adapter : cp .env.example .env
+# Lu par docker compose (substitution ${...} et env_file des services) ; avec la CLI
+# ou `serve` hors conteneur : set -a; . ./.env; set +a
+# Les lignes commentées donnent la valeur par défaut. Pour les secrets, préférer la
+# variante _FILE (secret docker monté dans /run/secrets) à une valeur en clair ici.
+
+# ---------- Commun ----------
+TZ=Europe/Paris
+# Port publié par docker-compose.demo.yml
+# CONFSYNC_PORT=8080
+
+# ---------- Interface web (pve-confsync serve) ----------
+# LISTEN=:8080
+# DATA_DIR=/data                       # base SQLite, secret.key, session.key
+# SESSION_TTL=12h                      # durée Go : 30m, 8h, 24h…
+# CONFSYNC_DEMO=false                  # true : faux clusters PVE, base temporaire
+
+# Clé AES-256 des secrets en base (64 caractères hex ou base64 de 32 octets) :
+#   openssl rand -hex 32
+# Ordre de lecture : CONFSYNC_SECRET_KEY, puis CONFSYNC_SECRET_KEY_FILE, sinon DATA_DIR/secret.key
+# (créée au 1er démarrage). Le compose fournit déjà CONFSYNC_SECRET_KEY_FILE ; une valeur
+# CONFSYNC_SECRET_KEY ici serait prioritaire. Sans cette clé, les secrets enregistrés sont perdus.
+# CONFSYNC_SECRET_KEY=
+# CONFSYNC_SECRET_KEY_FILE=/run/secrets/confsync_key
+
+# Premier administrateur, créé seulement si la base n'a aucun utilisateur.
+# Sans mot de passe fourni, il est tiré au hasard et écrit une fois dans les logs.
+# CONFSYNC_ADMIN_USER=admin
+# CONFSYNC_ADMIN_PASSWORD=
+# CONFSYNC_ADMIN_PASSWORD_FILE=/run/secrets/confsync_admin
+
+# Import initial du YAML de la CLI si la base n'a aucun cluster
+# CONFSYNC_IMPORT=/config/confsync.yaml
+
+# Comptes locaux (false exige OIDC)
+# AUTH_LOCAL=true
+
+# ---------- OIDC (optionnel ; actif dès que OIDC_ISSUER est renseigné) ----------
+# OIDC_ISSUER=https://auth.example.org/application/o/confsync/
+# OIDC_CLIENT_ID=confsync
+# OIDC_CLIENT_SECRET=
+# OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client
+# URL complète déclarée chez l'IdP ; son chemin devient la route de callback
+# OIDC_REDIRECT_URL=https://confsync.example.org/auth/callback
+# OIDC_SCOPES=openid profile email     # ajouter le scope qui fournit les groupes (ex. groups)
+# OIDC_GROUPS_CLAIM=groups
+# OIDC_ADMIN_GROUP=confsync-admins
+# OIDC_OPERATOR_GROUP=confsync-operators
+# OIDC_DEFAULT_ROLE=viewer             # admin, operator ou viewer
+
+# ---------- CLI (pve-confsync check | export | diff | apply) ----------
+# CONFSYNC_CONFIG=/config/confsync.yaml
+# Secrets des tokens référencés par token_secret_env dans confsync.yaml (un par cluster) :
+# PVE_SITE_B_SECRET=
diff --git a/README.md b/README.md
index fb702e6..f67e732 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,8 @@ mot de passe `confsync-demo`.
   utilisateurs locaux, import / export YAML (format de la CLI), compte, apparence.
 
 Rôles : `admin` (tout), `operator` (dry-run et synchronisation), `viewer` (lecture).
-Les comptes locaux restent disponibles même avec OIDC.
+Les comptes locaux restent disponibles même avec OIDC. Toutes les variables sont reprises,
+commentées, dans [`.env.example`](.env.example) (`cp .env.example .env`).
 
 | Variable | Défaut | Rôle |
 |---|---|---|