Variables d'Environnement

Le conteneur API Apprise est hautement configurable via des variables d’environnement.

Configuration d’Exécution

Variable	Défaut	Description
APPRISE_STATEFUL_MODE	hash	Contrôle le moteur de stockage persistant. simple : enregistre les configurations sous forme de fichiers lisibles (/config/{KEY}.yaml). Recommandé pour la plupart des utilisateurs. hash : enregistre les configurations sous forme de hachages indexés. Efficace à grand volume. disabled : désactive entièrement le stockage persistant (mode stateless uniquement). Les valeurs sont insensibles à la casse.
APPRISE_STATELESS_MODE	enabled	Contrôle les appels /notify/ sans état. enabled : accepte les requêtes. disabled : rejette les requêtes. Si les deux modes de notification sont désactivés, /status indique degraded.
APPRISE_WORKER_COUNT	(Auto)	Nombre de workers Gunicorn. La valeur par défaut est (2 * CPUs) + 1. Définissez 1 pour les environnements à faibles ressources.
APPRISE_WORKER_MAX_REQUESTS	1000	Nombre de requêtes traitées par un worker avant son recyclage. Le recyclage libère la mémoire accumulée. Réduisez cette valeur, par exemple à 100, si vos workers restent actifs longtemps et que la mémoire a tendance à croître.
APPRISE_WORKER_MAX_REQUESTS_JITTER	50	Décalage aléatoire ajouté à APPRISE_WORKER_MAX_REQUESTS pour éviter que tous les workers redémarrent ensemble.
APPRISE_WORKER_TIMEOUT	300	Délai d’expiration d’un worker, en secondes.
APPRISE_BASE_URL	(Aucun)	Définissez cette valeur si vous exécutez l’application derrière un proxy inverse sous un sous-chemin, par exemple /apprise.
APPRISE_ADMIN	yes	Affiche toutes les clés enregistrées via le point de terminaison /cfg et l’interface Web. Cela fonctionne uniquement si APPRISE_STATEFUL_MODE est défini sur simple. Définissez no pour masquer la liste.

Sécurité et Accès

Variable	Défaut	Description
STRICT_MODE	no	Conteneur uniquement. Autorise les routes Apprise connues, renvoie 404 pour les routes inconnues et 405 pour les méthodes non prises en charge, et applique des limites d’authentification renforcées qui renvoient 429 avec Retry-After.
APPRISE_CONFIG_LOCK	no	Masque le contenu et la gestion des configurations aux utilisateurs ordinaires. Les nouveaux comptes utilisent locked par défaut et l’accès user enregistré se comporte comme locked sans être réécrit. L’accès public reste public, car il masque déjà le contenu de la configuration.
APPRISE_AUTH_REQUIRED	no	Définissez yes pour activer l’authentification. Lorsqu’elle est désactivée, les paramètres d’administration et les connexions de configuration enregistrées sont ignorés. Voir Authentification et Contrôle d’Accès.
APPRISE_USER	(Aucun)	Nom d’utilisateur administrateur facultatif, utilisé uniquement avec APPRISE_AUTH_REQUIRED=yes. Il exige APPRISE_PASSWORD et ne peut pas contenir de deux-points.
APPRISE_PASSWORD	(Aucun)	Mot de passe administrateur facultatif, utilisé uniquement avec APPRISE_AUTH_REQUIRED=yes. Il peut être utilisé sans nom d’utilisateur. Laissez-le non défini pour autoriser uniquement les connexions de configuration existantes.
APPRISE_BASIC_AUTH_REALM	Apprise API	Nom affiché dans les invites Basic Auth. Il ne modifie pas les identifiants. Utilisez un nom différent pour chaque instance partageant un même hôte.
APPRISE_WEB_AUTH_SECRET	(Générée)	Clé facultative qui signe les connexions Web. Si elle n’est pas définie, une clé aléatoire est créée une seule fois et enregistrée dans .web_auth_secret au sein du dossier de configuration. Sa modification déconnecte les navigateurs sans déplacer les configurations en mode hash.
APPRISE_TRUSTED_ORIGINS	(Aucun)	Adresses publiques autorisées à effectuer des modifications depuis un navigateur, séparées par des virgules. Utilisez l’adresse complète scheme://host[:port], par exemple https://apprise.example.com. Les clients directs comme curl ne sont pas affectés.
ALLOWED_HOSTS	*	Liste, séparée par des espaces, des en-têtes Host autorisés.
APPRISE_DENY_SERVICES	(Liste par défaut)	Liste séparée par des virgules des schémas à bloquer. Par exemple, dbus, windows, macosx, gnome et syslog sont bloqués par défaut dans Docker.
APPRISE_ALLOW_SERVICES	(Tous)	Liste séparée par des virgules des schémas autorisés. Si elle est définie, seuls ces services fonctionneront.

Impact Mémoire du Filtrage des Services

APPRISE_ALLOW_SERVICES et APPRISE_DENY_SERVICES ne se contentent pas d’activer ou désactiver des schémas. L’API Apprise évince automatiquement de la mémoire les bibliothèques optionnelles lorsque tous les plugins qui en dépendent sont désactivés.

Chaque plugin de notification nécessitant une dépendance lourde déclare cette dépendance en interne. Lorsque le dernier plugin utilisant une bibliothèque donnée est désactivé, cette bibliothèque est retirée de l’exécution Python (sys.modules), ce qui libère les objets associés. Cela se produit au démarrage, avant la première requête.

Les bibliothèques concernées par l’éviction et leurs gains estimés sont les suivants :

Bibliothèque	Utilisée Par	Mémoire Libérée
slixmpp	xmpp://	~20 MB
paho	mqtt://	~4 MB
gntp	growl://	~2 MB
smpplib	smpp://, smpps://	~2 MB
hid	blink1://	~2 MB
pgpy	mailto://, mailtos:// (PGP uniquement)	~10 MB
cryptography	simplepush://, fcm://, vapid://	partielle†

†cryptography s’appuie nativement sur OpenSSL. Les objets d’encapsulation Python sont libérés, mais la bibliothèque partagée sous-jacente reste chargée par le système d’exploitation pendant toute la durée de vie du processus.

Exemple : un déploiement qui n’a besoin que de Telegram et NTFY :

APPRISE_ALLOW_SERVICES=tgram,ntfy

Cela désactive tous les autres plugins, ce qui provoque l’éviction de slixmpp, paho, gntp, smpplib, ainsi que des wrappers cryptography. Combiné avec APPRISE_WORKER_COUNT=1, cela permet de ramener un conteneur mono-worker depuis une base typique d’environ 180 MB à environ 145 MB.

Note

Ce comportement d’éviction est spécifique à l’API Apprise. La bibliothèque Python Apprise, lorsqu’elle est utilisée directement ou intégrée dans des projets tiers, n’évince pas les bibliothèques ; les plugins désactivés deviennent simplement inactifs, et les modules déjà chargés restent en mémoire.

Pour un guide complet sur la réduction de la mémoire conteneur et de la RAM, consultez Utilisation des Ressources.

Stockage et Limites

Variable	Défaut	Description
APPRISE_ATTACH_SIZE	200	Taille maximale des pièces jointes, en MB. Définissez 0 pour désactiver les pièces jointes.
APPRISE_UPLOAD_MAX_MEMORY_SIZE	3	Taille maximale, en MB, du corps de requête conservé en mémoire avant déversement sur disque.
APPRISE_CONFIG_MAX_LENGTH	512	Taille maximale de la charge utile de configuration, en KB. Ne peut pas dépasser APPRISE_UPLOAD_MAX_MEMORY_SIZE.
APPRISE_STREAM_MEMORY_SIZE	2	Journaux du flux et du résultat conservés en mémoire avant le stockage sur disque, en Mo.
APPRISE_STREAM_DISK_SIZE	256	Espace disque temporaire accordé à chaque flux et chaque résultat, en Mo.
APPRISE_STREAM_WORKER_COUNT	4	Flux actifs par processus worker Gunicorn. La valeur effective pour tout le serveur est APPRISE_WORKER_COUNT * 4.
APPRISE_STREAM_QUEUE_SIZE	8	Flux en direct supplémentaires pouvant rester en attente par processus worker Gunicorn.
APPRISE_RECURSION_MAX	1	Profondeur maximale de récursion pour les appels apprise:// vers d’autres serveurs.
APPRISE_ALLOW_TEMPLATES	yes	Autoriser une configuration YAML enregistrée à utiliser une section template: et à remplir les marqueurs ${NOM}. Voir la note ci-dessous.
APPRISE_TEMPLATE_<NOM>		Fournit ${NOM} dans un YAML enregistré sans valeur par défaut. Une valeur vide est ignorée.

Attention

APPRISE_TEMPLATE_<NOM> est partagé par toutes les configurations enregistrées sur le serveur. Utilisez des noms distincts pour les valeurs qui ne doivent pas être partagées. Définissez APPRISE_ALLOW_TEMPLATES=no pour désactiver les variables ; consultez Variables de substitution.

Réseau

Variable	Défaut	Description
HTTP_PORT	8000	Port interne du conteneur.
APPRISE_CONNECTION_TIMEOUT	600	Durée d’attente d’une activité du flux, en secondes (30 à 3600).
PUID	1000	Identifiant utilisateur sous lequel exécuter le service.
PGID	1000	Identifiant de groupe sous lequel exécuter le service.
IPV4_ONLY	no	Forcer l’utilisation d’IPv4 uniquement.
IPV6_ONLY	no	Forcer l’utilisation d’IPv6 uniquement.

Paramètres Supplémentaires de l’API Apprise

Le conteneur prend aussi en charge les variables suivantes, qui correspondent directement aux paramètres du serveur.

À propos de <BASE_DIR> dans les valeurs par défaut

<BASE_DIR> n’est pas une variable d’environnement : il s’agit du répertoire où l’application API Apprise est installée et exécutée, c’est-à-dire son répertoire de travail. Les chemins relatifs que vous définissez pour ces variables sont eux aussi résolus depuis ce même répertoire. Si vous devez stocker des données en dehors du répertoire d’installation, utilisez un chemin absolu, par exemple /data/apprise/config.

Variable	Défaut	Description
APPRISE_DEFAULT_CONFIG_ID	apprise	Clé de configuration par défaut utilisée par l’interface Web.
APPRISE_WEBHOOK_URL	(Vide)	Webhook facultatif recevant une charge utile POST après chaque tentative de notification.
APPRISE_CONFIG_DIR	<BASE_DIR>/var/config	Répertoire stockant les configurations. Relatif à <BASE_DIR> sauf si un chemin absolu est fourni.
APPRISE_STORAGE_DIR	<APPRISE_CONFIG_DIR>/store	Répertoire stockant le stockage persistant.
APPRISE_STORAGE_MODE	auto	Mode de stockage persistant. Valeurs possibles : memory, auto, flush. Les valeurs sont insensibles à la casse ; m, a et f sont acceptés comme raccourcis.
APPRISE_STORAGE_PRUNE_DAYS	30	Âge en jours avant que storeprune supprime l’état persistant. Voir Élagage.
APPRISE_STORAGE_UID_LENGTH	8	Longueur par défaut de l’identifiant d’URL utilisé par le stockage persistant.
APPRISE_AUTH_PRUNE_SECONDS	2592000	Âge en secondes avant que authprune supprime un verrou sans configuration. Les verrous avec configuration sont conservés.
APPRISE_PRUNE_INTERVAL_SECONDS	86400	Fréquence à laquelle le conteneur élague l’état persistant et les verrous d’authentification inutilisés.
APPRISE_PRUNE_TIMEOUT_SECONDS	28800	Durée maximale d’une exécution automatique d’élagage.
APPRISE_PRUNE_ENABLED	yes	Définissez no pour arrêter l’élagage planifié. Les commandes manuelles restent disponibles.
APPRISE_ATTACH_DIR	<BASE_DIR>/var/attach	Répertoire stockant les pièces jointes téléchargées. Relatif à <BASE_DIR> sauf si un chemin absolu est fourni.
APPRISE_ATTACH_SIZE	200	Taille maximale des pièces jointes, en MB. Définissez 0 pour désactiver les pièces jointes.
APPRISE_CONFIG_MAX_LENGTH	512	Taille maximale de la charge utile de configuration, en KB, acceptée par le formulaire et par les mises à jour de configuration via l’API. Indépendante de la limite du corps de requête. Ne peut pas dépasser APPRISE_UPLOAD_MAX_MEMORY_SIZE.
APPRISE_STREAM_MEMORY_SIZE	2	Volume des journaux du flux et du résultat conservé en mémoire avant d’utiliser le stockage temporaire sur disque, en Mo. Définissez 0 pour écrire directement sur disque.
APPRISE_STREAM_DISK_SIZE	256	Espace disque temporaire maximal utilisé par chaque flux et chaque résultat de notification, en Mo. Définissez 0 pour utiliser uniquement la mémoire sans limite. Définir les deux tailles de flux à 0 désactive la conservation des événements du flux en attente.
APPRISE_STREAM_WORKER_COUNT	4	Notifications diffusées actives par processus worker Gunicorn. La valeur effective par défaut pour tout le serveur est APPRISE_WORKER_COUNT * 4. Un envoi qui se poursuit après la déconnexion du client occupe toujours son emplacement.
APPRISE_STREAM_QUEUE_SIZE	8	Flux en direct supplémentaires pouvant rester connectés dans chaque processus worker Gunicorn pendant l’attente d’un emplacement actif ou la fin de leur réponse. Les suivants reçoivent le code 503 avec un en-tête Retry-After. Définissez 0 pour n’autoriser aucun flux supplémentaire.
APPRISE_MAX_ATTACHMENTS	6	Nombre maximal de pièces jointes par requête. Définissez 0 pour désactiver cette limite.
APPRISE_WEBHOOK_MAPPING_MAX_DEPTH	5	Profondeur maximale de traversée pour les règles de correspondance de champs imbriqués. Chaque étape individuelle est comptée, qu’il s’agisse d’une clé de dictionnaire ou d’un index de tableau ([N]). Par exemple, items[0].objectURI compte pour 3 étapes, tandis que a[0][1][2].value[3] en compte 6. Voir Hooks de Correspondance de Charge Utile.
APPRISE_ATTACH_ALLOW_URL	*	Liste d’autorisation pour les URL distantes de pièces jointes.
APPRISE_ATTACH_REJECT_URL	127.0.* localhost*	Liste de refus pour les URL distantes de pièces jointes, vérifiée avant la liste d’autorisation ci-dessus. Prend en charge les caractères génériques (*, ?). Ajoutez le mot-clé spécial internal pour aussi bloquer toute destination qui se résout vers une adresse privée ou interne (appareils du réseau local, métadonnées cloud, etc.), pas seulement les hôtes orthographiés 127.0.*/localhost*. Désactivé par défaut, car cela bloque aussi votre propre réseau local. Voir Pièces jointes.
APPRISE_STATELESS_URLS	(Vide)	URL par défaut utilisées par les requêtes stateless /notify/ lorsqu’aucune valeur urls n’est fournie.
APPRISE_STATELESS_STORAGE	no	Autoriser les requêtes stateless à utiliser le stockage persistant lorsqu’il est activé.
APPRISE_DENY_SERVICES	(Liste de plateforme)	Liste séparée par des virgules des schémas à désactiver.
APPRISE_ALLOW_SERVICES	(Vide)	Liste d’autorisation exclusive. Si elle est définie, tout ce qui n’en fait pas partie est désactivé.
APPRISE_PLUGIN_PATHS	<BASE_DIR>/var/plugin	Liste séparée par des virgules des chemins de plugins à analyser. Relative à <BASE_DIR> sauf si des chemins absolus sont fournis.
APPRISE_API_ONLY	no	Désactive l’interface Web et n’autorise que les points de terminaison API.
APPRISE_DEFAULT_THEME	light	Thème par défaut pour l’interface Web. Valeurs possibles : light, dark. Les valeurs sont insensibles à la casse ; l et d sont acceptés comme raccourcis.
APPRISE_INTERPRET_EMOJIS	(Non défini)	Si cette variable est définie, elle force l’interprétation des emojis. Valeurs possibles : yes ou no.
APPRISE_HTTP_REDIRECTS	yes	Suit les redirections HTTP par défaut. Définissez no pour les désactiver pour tous les services ; une URL peut remplacer ce choix avec ?redirect=yes ou ?redirect=no.
APPRISE_DEFAULT_FORMAT	(Non défini)	Format d’entrée par défaut lorsqu’une requête API omet format. Accepte text, html ou markdown (sans tenir compte de la casse). Non défini par défaut : aucune conversion automatique n’a lieu. Un champ vide ou null dans la requête désactive aussi la conversion. L’interface Web envoie toujours un format.

Django et Journalisation

Variable	Défaut	Description
SECRET_KEY	(Valeur intégrée)	Clé secrète Django. Remplacez toujours cette valeur en production.
DEBUG	no	Active le mode debug. Prend en charge yes, 1, true et autres variantes similaires.
LOG_LEVEL	INFO	Niveau par défaut des journaux Django, de la console et des notifications. X-Apprise-Log-Level peut demander un autre niveau pour une notification sans modifier la sortie de la console. Pour une configuration enregistrée, debug et trace exigent les droits d’administrateur ou l’accès user ; les accès locked, public et disabled sont limités à info.
TZ	Etc/UTC	Fuseau horaire appliqué à tous les horodatages des journaux. Tout nom de fuseau IANA est accepté, par exemple America/New_York ou Europe/London. Consultez la liste des fuseaux horaires de la base tz pour les valeurs valides. Tous les processus du conteneur (journalisation Python, nginx, etc.) héritent directement de TZ, de sorte que les horodatages restent cohérents que le conteneur s’exécute en tant que root ou non. Le montage de /etc/localtime ou /etc/timezone sans définir TZ n’est plus pris en charge. Définissez TZ avec le nom du fuseau souhaité à la place.
ALLOWED_HOSTS	*	Liste des hôtes autorisés, séparés par des espaces.
APPRISE_UPLOAD_MAX_MEMORY_SIZE	3	Taille maximale, en MB, du corps de requête conservé en mémoire avant que Django ne lève RequestDataTooBig.