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).
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 échelonner les redémarrages des workers et éviter un effet de troupeau.
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	no	Définissez yes pour activer le point de terminaison /cfg, ce qui permet d’afficher toutes les clés enregistrées dans l’interface Web. Cela fonctionne uniquement si APPRISE_STATEFUL_MODE est défini sur simple.

Sécurité et Accès

Variable	Défaut	Description
APPRISE_CONFIG_LOCK	no	Définissez yes pour rendre la configuration en lecture seule. Empêche l’ajout ou la modification de clés via l’API.
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_RECURSION_MAX	1	Profondeur maximale de récursion pour les appels apprise:// vers d’autres serveurs.

Réseau

Variable	Défaut	Description
HTTP_PORT	8000	Port interne du conteneur.
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.
APPRISE_STORAGE_PRUNE_DAYS	30	Nombre de jours avant l’élagage du stockage persistant.
APPRISE_STORAGE_UID_LENGTH	8	Longueur par défaut de l’identifiant d’URL utilisé par le stockage persistant.
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_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.
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.
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	Par défaut, Apprise suit les redirections HTTP 3xx, conformément au comportement de la bibliothèque requests. Définir à no pour désactiver le suivi des redirections pour tous les plugins sans toucher aux URLs individuelles. Les URLs individuelles peuvent toujours remplacer ce réglage via ?redirect=yes ou ?redirect=no.

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 de journalisation pour Django et pour les journaux Apprise.
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.