¶ Configuration et options
La configuration vient de deux sources, et l'ordre de priorité compte.
| Source | Contenu | Priorité |
|---|---|---|
L'environnement (.env, variables du conteneur, ConfigMap, Secret) |
tout | la plus basse |
data/settings.json, écrit par l'écran Administration → Réglages |
une liste fermée de champs | l'emporte |
Ce n'est pas une inversion accidentelle : le fichier de réglages vit dans le
volume de données, donc il survit au remplacement du conteneur. Changer l'URL de
Home Assistant depuis l'interface ne doit pas être défait au prochain
docker compose up.
Les champs non modifiables depuis l'interface — ENV, SECRET_KEY,
APP_TIMEZONE, LOG_FILE — restent du seul ressort de l'environnement : le mode
de déploiement, la clé de session et le fuseau ne se changent pas depuis un
navigateur.
¶ Application
| Variable | Défaut | Rôle |
|---|---|---|
ENV |
development |
development ou production. En production, deux garde-fous sont armés (voir plus bas) |
SECRET_KEY |
valeur d'exemple | signe le cookie de session, et dérive la clé de chiffrement des secrets persistés |
APP_TIMEZONE |
Europe/Paris |
fuseau de référence des plannings |
LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING, ERROR. Modifiable depuis l'interface, sans redémarrer |
LOG_FILE |
data/logs/scenario-studio.log |
fichier du journal applicatif |
¶ SECRET_KEY
Une seule clé pour deux usages : la signature du cookie de session, et — par
dérivation HKDF — le chiffrement des secrets écrits dans data/settings.json.
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
La changer invalide les sessions en cours et rend illisibles les secrets déjà
chiffrés : le jeton Home Assistant et le secret client OIDC devront être
ressaisis. L'application le dit explicitement plutôt que d'échouer en silence.
¶ APP_TIMEZONE
Les heures des plannings sont des heures d'horloge : « 22:30 » veut dire
22:30 à la pendule, avant comme après le changement d'heure. Ce fuseau est celui
dans lequel Home Assistant les interprétera. Ne le changez pas sans raison : les
plannings existants ne sont pas recalculés.
¶ LOG_FILE
Le journal est écrit dans ce fichier en plus de la sortie standard. C'est
nécessaire : la sortie d'un conteneur n'est pas relisible depuis l'application,
et c'est justement quand on n'a pas accès au terminal qu'on en a besoin. Le
fichier tourne par taille — 2 Mio, trois archives, donc 8 Mio au plus — il ne
remplira pas le disque et il n'y a rien à purger.
Placez-le dans le volume de données pour qu'il survive au redémarrage.
¶ Base de données
| Variable | Défaut | Rôle |
|---|---|---|
DATABASE_URL |
sqlite+aiosqlite:///./data/scenario_studio.db |
URL asynchrone de la base |
Deux moteurs :
sqlite+aiosqlite:////app/data/scenario_studio.db # chemin absolu : 4 slashes
postgresql+asyncpg://utilisateur:motdepasse@hote:5432/base
SQLite convient à un usage personnel. PostgreSQL devient utile quand plusieurs
personnes écrivent, ou quand on veut plus d'un exemplaire de l'application.
On ne change pas ce réglage seul : il faut d'abord copier les données, depuis
Administration → Base et sauvegardes. Voir Administration.
¶ Home Assistant
| Variable | Défaut | Rôle |
|---|---|---|
HA_BASE_URL |
— | URL de l'instance, sans slash final |
HA_TOKEN |
— | long-lived access token |
HA_TIMEOUT_S |
15 |
délai maximum des appels HTTP, en secondes |
HA_SYNC_DOMAINS |
light,switch,cover |
domaines rapatriés à la synchronisation |
L'URL WebSocket est déduite automatiquement (http → ws, https → wss) :
il n'y a rien d'autre à déclarer. Les registres — pièces et appareils — ne sont
accessibles que par cette API.
¶ Le jeton
Home Assistant → profil utilisateur → Jetons d'accès longue durée → Créer.
Ce jeton donne un contrôle total sur l'instance. Traitez-le comme un mot de
passe d'administration : il n'a rien à faire dans un dépôt, ni dans un ConfigMap.
Une fois saisi depuis l'interface, il est chiffré dans data/settings.json et ne
s'affiche plus nulle part — ni à l'écran, ni dans les messages d'erreur, ni dans
le journal.
¶ Les domaines synchronisés
HA_SYNC_DOMAINS décide quels domaines pilotables sont rapatriés. Les
capteurs sont toujours rapatriés, quel que soit ce réglage : sans eux les
routines de contrôle seraient muettes, et faire dépendre une fonctionnalité d'un
réglage enregistré avant son existence n'aurait aucun sens.
¶ Prérequis côté Home Assistant
Pour que l'API de configuration accepte d'écrire des automatisations, le
configuration.yaml de Home Assistant doit inclure :
automation: !include automations.yaml
Sans cette ligne, l'API renvoie une erreur et aucun déploiement n'est possible.
L'application vérifie ce prérequis et l'affiche dans le tableau de bord.
¶ Authentification
| Variable | Défaut | Rôle |
|---|---|---|
AUTH_MODE |
local |
local, oidc ou dev |
DEV_USER_EMAIL |
dev@localhost |
identité utilisée en mode dev |
DEV_USER_NAME |
Administrateur local |
idem |
OIDC_ISSUER |
— | URL du realm Keycloak |
OIDC_CLIENT_ID |
— | identifiant du client |
OIDC_CLIENT_SECRET |
— | secret du client confidentiel |
OIDC_SCOPES |
openid profile email groups |
portées demandées |
OIDC_GROUPS_CLAIM |
groups |
nom du claim de groupes dans l'ID token |
OIDC_ADMIN_GROUP |
— | appartenir à ce groupe donne le rôle Administration |
Le détail — modes, rôles, configuration du client Keycloak — est sur la page
Authentification et rôles.
¶ Garde-fous
| Variable | Défaut | Rôle |
|---|---|---|
ALLOW_STEP_TEST |
false |
autorise le « test d'une étape », qui exécute réellement ses actions dans Home Assistant |
C'est la seule option qui permet à l'application d'envoyer un ordre à un
équipement, et elle est désactivée par défaut. En fonctionnement normal,
l'application n'émet que automation.turn_on, automation.turn_off et
automation.reload.
¶ Deux refus au démarrage
Vérifiés avant que l'application ne serve la moindre requête ; s'ils ne sont pas
respectés, elle ne démarre pas du tout :
| Condition | Raison |
|---|---|
AUTH_MODE=dev et ENV=production |
ce mode donne un accès administrateur sans aucune authentification |
SECRET_KEY d'exemple ou trop courte et ENV=production |
un cookie de session signé avec une clé publique n'est pas signé |
Un refus au démarrage est bruyant et se voit tout de suite. Le même défaut
toléré ne se voit jamais — jusqu'au jour où il se voit trop.
¶ Réglages modifiables depuis l'interface
Administration → Réglages et connexions. Ces champs sont écrits dans
data/settings.json et l'emportent sur l'environnement :
database_url · ha_base_url · ha_token · ha_timeout_s · ha_sync_domains ·
auth_mode · oidc_issuer · oidc_client_id · oidc_client_secret ·
oidc_scopes · oidc_groups_claim · oidc_admin_group · allow_step_test ·
log_level · dev_mode
ha_token et oidc_client_secret y sont chiffrés (Fernet, clé dérivée de
SECRET_KEY par HKDF). Ce n'est pas une protection contre quelqu'un qui a déjà
le fichier et la clé ; c'est ce qui évite qu'un jeton se retrouve en clair dans
une sauvegarde, un partage d'écran ou une capture d'écran de support.
Chaque bloc a son bouton Tester : une configuration qu'on ne peut pas
éprouver se vérifie au pire moment, pendant un déploiement.
¶ Fichier .env complet
.env.example, à la racine du dépôt, documente chaque variable avec son
commentaire. Il ne contient que des valeurs d'exemple : aucun secret n'est
versionné, et .env est ignoré par git.
¶ Aller plus loin
- Authentification et rôles
- Administration — l'écran de réglages en usage
- Exploitation et dépannage
¶ Sommaire de la documentation
- Accueil Domodrive
- Domodrive — présentation
- Installation avec Docker
- Installation sur Kubernetes
- Configuration et options (page courante)
- Authentification et rôles
- Prise en main
- Plannings
- Routines de contrôle environnemental
- Périodes et déploiement
- Administration
- Exploitation et dépannage
- Référence technique
Documentation Domodrive 1.0.0 — copie conforme du répertoire docs/ du dépôt gitlab.ev1.fr/ev1/domodrive (dépôt privé).