Aller au contenu principal

Référence de configuration

Référence complète de toutes les variables d'environnement disponibles pour le backend et le frontend. Les variables sont configurées via deux fichiers à la racine du projet : .env (backend, workers, scheduler) et frontend.env (frontend).

Les variables requises pour le démarrage sont décrites dans le guide d'installation OpenVLE. Cette page sert de référence pour toutes les options disponibles.

Dans les tableaux, Oui = toujours requis et Oui* = requis lorsque la fonctionnalité correspondante est activée.

info

Toutes les variables du backend doivent être définies entre guillemets (" "), sans quoi des erreurs d'analyse se produiront au démarrage. Après chaque modification, les conteneurs doivent être redémarrés : docker compose down && docker compose up -d.

Backend (.env)

Général

Paramètres de base de l'application. CORS_ORIGINS est la seule variable requise dans cette catégorie — elle doit contenir l'URL à laquelle le frontend est accessible, sinon le navigateur bloquera les requêtes API. Les autres variables contrôlent le nom du projet affiché, les informations de contact et l'environnement (production/développement).

VariableValeur par défautRequisDescription
API_HEALTH_TOKEN""NonJeton d'authentification pour les requêtes de health check
APP_ENV"prod"NonEnvironnement (par ex. prod, dev)
CONTACT_MAIL"support@inett.de"NonE-mail de contact
CONTACT_NAME"inett GmbH"NonNom de la personne/organisation de contact
CONTACT_URL"https://inett.de"NonSite web de contact
CORS_ORIGINS[""]OuiOrigines autorisées pour CORS (URL du frontend)
DOCS_ENABLEDFalseNonActiver les endpoints OpenAPI (/docs, /redoc, /openapi.json)
PROJECT_DESCRIPTION"Kursverwaltungssoftware - Backend"NonDescription du projet
PROJECT_NAME"OpenVLE"NonNom interne du projet
PROJECT_TITLE"OpenVLE"NonTitre affiché dans l'interface
PROJECT_VERSION1.0NonVersion du projet

Authentification

Contrôle les sessions utilisateur et l'authentification basée sur des jetons. AUTH_SECRET et SESSION_SECRET_TOKEN doivent être définis sur des chaînes aléatoires et sécurisées — ils protègent les jetons JWT et les données de session. Un changement de AUTH_SECRET déconnecte immédiatement tous les utilisateurs actifs.

VariableValeur par défautRequisDescription
AUTH_ACCESS_TOKE_EXPIRE_MINUTES480NonDurée d'expiration des Access Tokens (minutes)
AUTH_ALOGORITHM"HS256"NonAlgorithme pour l'authentification JWT
AUTH_SECRET""OuiClé secrète pour l'authentification JWT
SESSION_SECRET_TOKEN""OuiJeton secret pour la gestion des sessions

Base de données — MariaDB

MariaDB est la base de données relationnelle principale et stocke toutes les entités centrales : utilisateurs, rôles, permissions, environnements, événements, VM, modèles de VM et connexions. Les informations de connexion doivent correspondre à l'instance MariaDB dans le stack Docker Compose. Les paramètres de pool contrôlent le nombre de connexions simultanées à la base de données que le backend maintient ouvertes — les valeurs par défaut sont suffisantes pour la plupart des installations.

VariableValeur par défautRequisDescription
MARIADB_CHARSET"utf8mb4"NonJeu de caractères
MARIADB_DATABASE"project"OuiNom de la base de données
MARIADB_HOST"db"OuiNom d'hôte du serveur MariaDB
MARIADB_IMAGE_TAG"11.2"NonTag de l'image Docker
MARIADB_PASSWORD"project"OuiMot de passe
MARIADB_POOL_ACQUIRE15000NonDélai d'acquisition (ms)
MARIADB_POOL_IDLE60000NonDélai d'inactivité (ms)
MARIADB_POOL_MAX12NonConnexions maximales dans le pool
MARIADB_POOL_MIN2NonConnexions minimales dans le pool
MARIADB_PORT3306OuiPort MariaDB
MARIADB_QUERY_RESULT_LIMIT200NonMax. enregistrements par requête
MARIADB_ROOT_PASSWORD""OuiMot de passe root de l'instance MariaDB
MARIADB_TIMEOUT120NonDélai de connexion (secondes)
MARIADB_TYPE"mysql"OuiType de base de données
MARIADB_USER"project"OuiNom d'utilisateur

Base de données — MongoDB

MongoDB stocke les activités, les événements système et les journaux d'audit. Ces données sont utilisées pour l'aperçu des activités dans l'interface utilisateur. Les informations de connexion doivent correspondre à l'instance MongoDB dans le stack Docker Compose.

VariableValeur par défautRequisDescription
MONGODB_DATABASE"project"OuiNom de la base de données
MONGODB_HOST"localhost"OuiNom d'hôte du serveur MongoDB
MONGODB_IMAGE_TAG"jammy"NonTag de l'image Docker
MONGODB_PASSWORD"project"OuiMot de passe
MONGODB_PORT27017OuiPort
MONGODB_USER"project"OuiNom d'utilisateur

Base de données — Redis

Redis sert de file d'attente de tâches et de cache pour les processus Worker et Scheduler. Toutes les tâches asynchrones (opérations VM, envoi d'e-mails, tâches périodiques) sont distribuées via les files Redis.

VariableValeur par défautRequisDescription
REDIS_DATABASE0OuiIndex de la base de données
REDIS_HOST"localhost"OuiNom d'hôte du serveur Redis
REDIS_IMAGE_TAG"latest"NonTag de l'image Docker
REDIS_PASSWORD"password"OuiMot de passe
REDIS_PORT6379OuiPort
REDIS_USERNAME"username"OuiNom d'utilisateur

Proxmox VE

Configure la connexion à Proxmox VE, l'hyperviseur qui gère les machines virtuelles. Les identifiants (utilisateur, jeton) doivent correspondre à la configuration de l'intégration Proxmox VE.

Les paramètres réseau et VM (PVE_VMS_*) déterminent la configuration des VM nouvellement créées : dans quel pool elles sont placées, quel réseau et sous-réseau elles utilisent, et si Cloud-Init est utilisé pour la configuration automatique.

VariableValeur par défautRequisDescription
PVE_API_POLL_RATE5NonIntervalle d'interrogation de l'API (secondes)
PVE_CI_DRIVE"cephssd"NonStockage pour le lecteur Cloud-Init
PVE_CI_ENABLEDFalseNonActiver Cloud-Init lors de la création de VM
PVE_FQDN"domain.intern"OuiFQDN du serveur Proxmox
PVE_HOSTNAME"proxmox:8006"OuiNom d'hôte et port du serveur Proxmox
PVE_TOKEN_NAME"my-token"OuiNom du jeton API
PVE_TOKEN_VALUE"my-token-secret"OuiValeur secrète du jeton API
PVE_USER"user@pve"OuiUtilisateur Proxmox
PVE_VERIFY_SSLTrueNonVérifier les certificats SSL
PVE_VM_SUBNET"0.0.0.0/16"OuiSous-réseau pour les VM
PVE_VMS_CIPASSWORD""NonMot de passe Cloud-Init
PVE_VMS_CIUPGRADEFalseNonMise à jour système au démarrage de la VM
PVE_VMS_CIUSER"user"NonNom d'utilisateur Cloud-Init
PVE_VMS_DNS_DOMAIN""NonDomaine DNS pour les VM
PVE_VMS_DNS_SERVER"1.1.1.1"NonServeur DNS pour les VM
PVE_VMS_EXCLUDED_IPS""NonAdresses exclues de l'attribution d'IP. Liste séparée par des virgules d'IP, de plages d'IP (1-254) et de CIDR (/24). Défaut : 172.20.0.200, 172.20.0.1-172.20.0.254, 172.20.100.0/24
PVE_VMS_FULL_CLONE_DEFAULTFalseNonFull Clones par défaut au lieu de Linked Clones
PVE_VMS_GATEWAY""NonPasserelle pour les réseaux VM
PVE_VMS_NETWORK""OuiConfiguration réseau pour les VM
PVE_VMS_POOL"OpenVLE-VMs"OuiPool Proxmox pour les VM gérées
PVE_VMS_SMBIOS_METADATATrueNonTransmettre les métadonnées VM au système d'exploitation invité via SMBIOS
PVE_VMS_SUBNET"/24"NonTaille du sous-réseau

E-mail / SMTP

OpenVLE envoie des e-mails système pour différents événements : notifications d'événements et messages de statut pour les opérations VM. Un serveur SMTP fonctionnel est requis pour l'exploitation en production. MAIL_MAX_AGE_WEEKS contrôle la durée de conservation des e-mails envoyés dans la base de données avant leur suppression automatique.

VariableValeur par défautRequisDescription
MAIL_MAX_AGE_WEEKS4NonDurée de conservation des e-mails (semaines)
SMTP_FROM_MAIL"OpenVLE@example.com"OuiAdresse de l'expéditeur
SMTP_FROM_NAME"OpenVLE"OuiNom d'affichage de l'expéditeur
SMTP_HOST"localhost"OuiNom d'hôte du serveur SMTP
SMTP_METHOD"ssl"OuiMéthode de connexion (SSL/TLS)
SMTP_PASSWORD"password"OuiMot de passe SMTP
SMTP_PORT465OuiPort SMTP
SMTP_USERNAME"username"OuiNom d'utilisateur SMTP

Événements

Contrôle le déploiement automatique et le nettoyage des événements. Le délai de préparation (PREP_TIME_DAYS) détermine combien de jours avant la date de début ou après la date de fin d'un événement les processus automatiques (création de VM, suppression de VM) sont déclenchés. Avec EVENTS_START_REQUIRE_STUDENTS, il est possible de définir si un événement ne démarre que lorsqu'au moins un participant est affecté.

VariableValeur par défautRequisDescription
EVENTS_END_PREP_TIME_DAYS7NonJours avant la fin de l'événement pour les post-traitements
EVENTS_START_PREP_TIME_DAYS7NonJours avant le début de l'événement pour les préparations
EVENTS_START_REQUIRE_STUDENTSFalseNonNe démarrer l'événement que lorsqu'il y a des participants

Worker

Le processus Worker exécute les tâches asynchrones en arrière-plan : opérations VM (clonage, démarrage, arrêt), envoi d'e-mails et gestion des connexions Guacamole. Le Scheduler déclenche des tâches périodiques, par exemple la synchronisation régulière des informations des nœuds Proxmox. WORKER_MAX_RETRY contrôle le nombre de tentatives automatiques pour un job échoué avant qu'il ne soit marqué comme définitivement échoué.

VariableValeur par défautRequisDescription
WORKER_MAX_RETRY5NonMax. tentatives pour les jobs échoués
WORKER_PVE_PERIODIC_INTERVAL60NonIntervalle des jobs Proxmox périodiques (secondes)

Apache Guacamole (optionnel)

Optionnel

Ces variables ne sont requises que si Apache Guacamole est utilisé pour l'accès bureau à distance. Sans Guacamole, OpenVLE peut toujours être utilisé pour gérer les VM et les modèles de VM — cependant, l'accès bureau à distance via le navigateur ne sera pas disponible.

OpenVLE se connecte à la base de données Guacamole via ces identifiants pour créer, mettre à jour et supprimer automatiquement des connexions. Le CONNECTIONS_PREFIX permet de distinguer les connexions de différentes instances OpenVLE sur le même serveur Guacamole.

VariableValeur par défautRequisDescription
GUACAMOLE_CONNECTIONS_PREFIX""NonPréfixe pour les connexions créées automatiquement
GUACAMOLE_CONNECTIONS_PREFIX_EVENTSFalseNonPréfixe également pour les connexions d'événements
GUACAMOLE_DB"mysql"Oui*Type de base de données Guacamole
GUACAMOLE_PASSWORD"OpenVLE"Oui*Mot de passe du compte OpenVLE
GUACAMOLE_URL"http://openvle-guacamole:8080"Oui*URL du serveur Guacamole
GUACAMOLE_USER"OpenVLE"Oui*Nom d'utilisateur du compte OpenVLE dans Guacamole

Paramètres de connexion — Général

Ces variables contrôlent les valeurs par défaut des connexions Guacamole créées automatiquement. Elles sont utilisées comme configuration par défaut lors de la création de nouvelles connexions et peuvent être adaptées par type de connexion (RDP, VNC, SSH).

VariableValeur par défautDescription
GUACAMOLE_CONN_TIMEZONEEurope/BerlinFuseau horaire des connexions

Paramètres de connexion — RDP

Valeurs par défaut pour les connexions RDP (Remote Desktop Protocol). Ces paramètres contrôlent la qualité d'affichage, les autorisations de transfert de fichiers et la disposition du clavier pour l'accès bureau à distance.

VariableValeur par défautDescription
GUACAMOLE_RDP_COLOR_DEPTH32Profondeur de couleur en bits (8, 16, 24 ou 32)
GUACAMOLE_RDP_DISABLE_BITMAP_CACHINGFalseDésactiver la mise en cache des bitmaps
GUACAMOLE_RDP_DISABLE_DOWNLOADTrueEmpêcher le téléchargement de fichiers depuis le bureau à distance
GUACAMOLE_RDP_DISABLE_GFXFalseDésactiver le pipeline GFX
GUACAMOLE_RDP_DISABLE_OFFSCREEN_CACHINGFalseDésactiver la mise en cache hors écran
GUACAMOLE_RDP_DISABLE_UPLOADTrueEmpêcher l'envoi de fichiers vers le bureau à distance
GUACAMOLE_RDP_ENABLE_AUDIO_INPUTFalseActiver la redirection du microphone
GUACAMOLE_RDP_ENABLE_DESKTOP_COMPOSITIONFalseActiver la composition du bureau (Aero)
GUACAMOLE_RDP_ENABLE_DRIVEFalseActiver la redirection de lecteur (transfert de fichiers)
GUACAMOLE_RDP_ENABLE_FONT_SMOOTHINGFalseActiver le lissage des polices (ClearType)
GUACAMOLE_RDP_ENABLE_FULL_WINDOW_DRAGTrueAfficher le contenu de la fenêtre lors du déplacement
GUACAMOLE_RDP_ENABLE_MENU_ANIMATIONSFalseActiver les animations de menu
GUACAMOLE_RDP_ENABLE_PRINTINGFalseActiver la redirection d'imprimante
GUACAMOLE_RDP_ENABLE_THEMINGFalseActiver les effets de thème Windows
GUACAMOLE_RDP_ENABLE_WALLPAPERTrueAfficher l'image d'arrière-plan du bureau
GUACAMOLE_RDP_IGNORE_CERTTrueNe pas valider le certificat du serveur RDP
GUACAMOLE_RDP_PRINTER_NAMEPrinter-NameNom de l'imprimante redirigée
GUACAMOLE_RDP_RESIZE_METHODreconnectMéthode de redimensionnement de la fenêtre (reconnect ou display-update)
GUACAMOLE_RDP_SECURITY""Mode de sécurité RDP (vide = automatique, nla, tls, rdp, any)
GUACAMOLE_RDP_SERVER_LAYOUTde-de-qwertzDisposition du clavier (par ex. de-de-qwertz, en-us-qwerty)
Qualité d'affichage vs. performance

Les options pour le fond d'écran, la composition du bureau, le lissage des polices, le thème et les animations de menu améliorent le rendu visuel, mais augmentent la bande passante nécessaire. Pour les connexions à bande passante limitée, il est recommandé de laisser ces options désactivées.

Transfert de fichiers

Par défaut, l'envoi et le téléchargement sont désactivés (DISABLE_DOWNLOAD=True, DISABLE_UPLOAD=True). N'activez ces options que si le transfert de fichiers entre l'utilisateur et la VM est souhaité. Pour cela, ENABLE_DRIVE=True doit également être défini.

Paramètres de connexion — VNC

Valeurs par défaut pour les connexions VNC (Virtual Network Computing).

VariableValeur par défautDescription
GUACAMOLE_VNC_COLOR_DEPTH32Profondeur de couleur en bits

Paramètres de connexion — SSH / SFTP

Valeurs par défaut pour les connexions SSH et SFTP. Les valeurs SERVER_ALIVE_INTERVAL contrôlent l'intervalle de keep-alive pour empêcher les connexions inactives d'expirer.

VariableValeur par défautDescription
GUACAMOLE_SFTP_SERVER_ALIVE_INTERVAL30Intervalle de keep-alive pour les connexions SFTP (secondes)
GUACAMOLE_SSH_SERVER_ALIVE_INTERVAL30Intervalle de keep-alive pour les connexions SSH (secondes)

LDAP (optionnel)

Optionnel

Ces variables ne sont requises que si les utilisateurs doivent s'authentifier via un serveur LDAP existant (par ex. Active Directory, OpenLDAP). Lorsque LDAP est activé, les utilisateurs peuvent se connecter avec leurs identifiants existants sans avoir besoin d'un mot de passe OpenVLE séparé.

VariableValeur par défautRequisDescription
LDAP_ATTR_MAIL"mail"NonAttribut LDAP pour l'e-mail
LDAP_ATTR_USER"uid"NonAttribut LDAP pour le nom d'utilisateur
LDAP_DN_PEOPLE"ou=people,dc=org,dc=de"Oui*DN pour la recherche de personnes
LDAP_ENABLEDFalseNonActiver l'authentification LDAP
LDAP_HOST"localhost"Oui*Nom d'hôte du serveur LDAP
LDAP_PORT389Oui*Port
LDAP_VERIFY_SSLTrueNonVérifier les certificats SSL

OIDC (optionnel)

Optionnel

Ces variables ne sont requises que si les utilisateurs doivent s'authentifier via un fournisseur OpenID Connect (par ex. Keycloak, Azure AD, Google). OIDC permet le Single Sign-On (SSO) — les utilisateurs se connectent via le fournisseur d'identité externe et sont automatiquement enregistrés dans OpenVLE si nécessaire (OIDC_ENROLL_USERS).

VariableValeur par défautRequisDescription
OIDC_ALLOWED_REDIRECT_URLS[""]NonURL de redirection autorisées
OIDC_ATTR_EMAIL"email"NonAttribut pour l'e-mail
OIDC_ATTR_NAME"name"NonAttribut pour le nom d'affichage
OIDC_ATTR_USERNAME"sub"NonAttribut pour le nom d'utilisateur
OIDC_CLIENT_ID""Oui*Client-ID
OIDC_CLIENT_SECRET""Oui*Client-Secret
OIDC_ENABLEDFalseNonActiver l'authentification OIDC
OIDC_ENROLL_USERSTrueNonEnregistrer automatiquement les utilisateurs à la première connexion
OIDC_SCOPES"openid email profile"NonScopes OIDC
OIDC_URL_METADATA""Oui*URL du document de métadonnées OIDC

Moodle (optionnel)

Optionnel

Ces variables ne sont requises que si OpenVLE doit être connecté à une instance Moodle. Si cette fonctionnalité n'est pas utilisée, tous les éléments liés à Moodle ne sont pas affichés dans l'interface utilisateur. L'intégration est désactivée par défaut.

VariableValeur par défautRequisDescription
MOODLE_COURSE_VISIBLE"True"NonVisibilité des cours Moodle dupliqués
MOODLE_DELETE_COURSE_ON_EVENT_DELETE"False"NonSupprimer le cours Moodle lorsque l'événement est supprimé
MOODLE_ENABLEDFalseNonActiver l'intégration Moodle
MOODLE_SYNC_TIMEOUT"10"NonDélai d'expiration des tâches de synchronisation (secondes)
MOODLE_TIMEOUT"30"NonDélai d'expiration des requêtes API (secondes)
MOODLE_TOKEN""Oui*Jeton API Web Services
MOODLE_URL""Oui*URL de l'instance Moodle (sans barre oblique finale)
MOODLE_USER_AUTH"manual"NonMéthode d'authentification pour les utilisateurs Moodle nouvellement créés (par ex. ldap, oauth2, manual)
MOODLE_USER_MATCH_FIELD"email"NonChamp de correspondance entre les utilisateurs OpenVLE et Moodle (email ou username)
MOODLE_VERIFY_SSLTrueNonVérifier le certificat SSL

Sentry (optionnel)

Optionnel

Ces variables ne sont requises que si Sentry doit être activé pour la surveillance des erreurs et le suivi des performances. Sentry capture automatiquement les exceptions, les traces et les profils de performance du backend et du worker — aussi bien dans les environnements de développement que de production. OpenVLE ne fournit pas de point de terminaison Sentry public. Vous pouvez renseigner ici les valeurs DSN de votre propre instance Sentry (on-premise ou SaaS).

VariableValeur par défautRequisDescription
SENTRY_BACKEND_DSN""Oui*DSN pour le projet backend
SENTRY_BACKEND_ENABLE_TRACINGTrueNonActiver le tracing
SENTRY_BACKEND_ENABLEDFalseNonActiver Sentry pour le backend
SENTRY_BACKEND_PROFILES_SAMPLE_RATE1.0NonTaux d'échantillonnage des profils
SENTRY_BACKEND_TRACES_SAMPLE_RATE1.0NonTaux d'échantillonnage des traces
SENTRY_ENV"dev"NonEnvironnement (par ex. dev, prod)
SENTRY_WORKER_DSN""Oui*DSN pour le projet worker
SENTRY_WORKER_ENABLE_TRACINGTrueNonActiver le tracing
SENTRY_WORKER_ENABLEDFalseNonActiver Sentry pour le worker
SENTRY_WORKER_PROFILES_SAMPLE_RATE1.0NonTaux d'échantillonnage des profils
SENTRY_WORKER_TRACES_SAMPLE_RATE1.0NonTaux d'échantillonnage des traces

Frontend

La configuration du frontend se fait via le fichier frontend.env. Seule VITE_BACKEND_URL est requise — elle doit pointer vers l'URL du backend à laquelle le frontend envoie les requêtes API (par ex. https://openvle.example.com/v1). Toutes les autres variables concernent l'intégration optionnelle de Sentry pour le suivi des erreurs côté client dans le navigateur.

VariableValeur par défautRequisDescription
VITE_BACKEND_URL'http://localhost:8000/v1'OuiURL de l'API backend
VITE_SENTRY_DSN''NonDSN Sentry
VITE_SENTRY_ENABLED'false'NonActiver Sentry
VITE_SENTRY_ENV'dev'NonEnvironnement Sentry
VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE1.0NonTaux d'échantillonnage pour les replays en cas d'erreur
VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE1.0NonTaux d'échantillonnage pour les replays de session
VITE_SENTRY_REPORT_ERROR_ENABLED'false'NonActiver le rapport d'erreurs
VITE_SENTRY_REPORT_USER_ENABLED'false'NonActiver le rapport utilisateur
VITE_SENTRY_TRACE_PROPAGATION_TARGETS['localhost']NonCibles pour la propagation des traces
VITE_SENTRY_TRACES_SAMPLE_RATE1.0NonTaux d'échantillonnage des traces
VITE_SENTRY_TRANSMIT_USER_DETAILS'false'NonTransmettre les informations détaillées de l'utilisateur

Dépannage

ProblèmeSolution
Le backend ne démarre pas après une modification .envAssurez-vous que toutes les valeurs sont entre guillemets. Les guillemets manquants provoquent des erreurs d'analyse.
La connexion à la base de données échoueVérifiez que MARIADB_HOST, MARIADB_PORT, MARIADB_USER et MARIADB_PASSWORD sont correctement définis et que le conteneur de base de données est en cours d'exécution.
Erreur CORS dans le navigateurAssurez-vous que CORS_ORIGINS contient l'URL de votre frontend (par ex. ["https://openvle.example.com"]).
La modification d'une variable n'a aucun effetLes conteneurs doivent être redémarrés après les modifications .env : docker compose down && docker compose up -d.