Configuration

Tout passe par des variables d'environnement. Le fichier .env à la racine alimente Docker Compose, l'API et le worker.

L'API lit ses réglages avec pydantic-settings (e-learning-api/src/e_learning/infrastructure/config.py) : toute variable préfixée APP_ surcharge la valeur par défaut. Hors Docker, elle lit .env.template puis .env dans son dossier.

Docker Compose#

Variable	Défaut du template	Rôle
`VIDEOS_HOST_PATH`	`./e-learning-api/videos`	Dossier hôte des médias, monté sur `/app/videos`
`POSTGRES_USER` / `_PASSWORD` / `_DB`	`elearning`	Identifiants de la base créée au premier démarrage
`POSTGRES_PORT`	`5432`	Port publié sur l'hôte
`API_PORT`	`8000`	Port publié de l'API
`FRONT_PORT`	`3000`	Port publié du front
`RABBITMQ_PORT` / `RABBITMQ_MANAGEMENT_PORT`	`5672` / `15672`	Broker et console web
`RABBITMQ_USER` / `RABBITMQ_PASSWORD`	`guest`	À changer dès que le port sort de la machine
`QDRANT_PORT`	`6333`	Port publié de Qdrant

API et worker#

Variable	Défaut	Rôle
`APP_DATABASE_URL`	Postgres local	URL SQLAlchemy async (`postgresql+asyncpg://…`)
`APP_VIDEOS_PATH`	`videos/`	Racine du catalogue sur disque (forcée à `/app/videos` par le compose)
`APP_DEBUG`	`false`	Active `/api-docs` et `/api-redoc`, et tolère les secrets d'exemple (avec un avertissement). Ne contourne pas l'authentification
`APP_LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`APP_CORS_ORIGINS`	`[]`	Liste JSON des origines du front, ex. `["http://localhost:3000"]`. `"*"` est refusé au démarrage : le cookie de session exige une liste explicite
`APP_INIT_DB`	`false`	`create_all` au démarrage ; préférer les migrations
`APP_RECONCILE_ON_STARTUP`	`false`	Réconcilie disque et base au démarrage
`APP_MAX_UPLOAD_SIZE`	`524288000`	Taille maximale d'un téléversement, en octets (500 Mo)
`APP_DB_POOL_SIZE` / `APP_DB_MAX_OVERFLOW`	`10` / `20`	Pool de connexions
`APP_ECHO_SQL`	`false`	Journalise chaque requête SQL

Authentification#

Variable	Défaut	Rôle
`APP_SECRET_KEY`	`changethis`	Clé de signature des jetons (JWT HS256). Au moins 32 caractères, ex. `openssl rand -hex 32`
`APP_ACCESS_TOKEN_EXPIRE_MINUTES`	`10080`	Durée d'une session (7 jours). Pas de rafraîchissement : il faut se reconnecter ensuite
`APP_FIRST_ADMIN_EMAIL`	`admin@example.com`	Premier administrateur, créé au démarrage s'il n'existe pas
`APP_FIRST_ADMIN_PASSWORD`	`changethis`	Son mot de passe initial ; jamais réécrit ensuite, même si la variable change
`APP_LOGIN_MAX_FAILURES` / `APP_LOGIN_WINDOW_MINUTES`	`5` / `15`	Échecs de connexion tolérés par email ou par IP sur la fenêtre, avant `429`
`APP_INSECURE_COOKIE_HOSTS`	`["localhost","127.0.0.1","::1"]`	Hôtes de l'API où le cookie de session n'est pas marqué `Secure` en HTTP. Ajoutez-y l'IP d'un serveur de réseau local sans HTTPS ; le jeton circule alors en clair

Démarrage refusé avec les valeurs d'exemple Hors APP_DEBUG=true, l'API ne démarre pas si APP_SECRET_KEY vaut changethis ou fait moins de 32 caractères, ou si APP_FIRST_ADMIN_PASSWORD vaut changethis. Changer la clé invalide toutes les sessions en cours.

Le compteur d'échecs de connexion vit en mémoire du processus de l'API : il repart à zéro au redémarrage. Derrière un reverse proxy, l'adresse IP comptée est celle du proxy.

Modèle de langage#

Utilisé pour les résumés et les réponses de l'assistant. N'importe quel point d'accès qui parle l'API /v1/chat/completions d'OpenAI convient.

Variable	Défaut	Rôle
`APP_OPENAI_BASE_URL`	`http://localhost:1234/v1`	Point d'accès (LM Studio par défaut)
`APP_OPENAI_API_KEY`	`lm-studio`	Clé envoyée au point d'accès
`APP_OPENAI_MODEL`	`openapi/gpt-oss-20b`	Nom du modèle

Assistant et embeddings#

Variable	Défaut	Rôle
`APP_QDRANT_URL`	`http://localhost:6333`	Instance Qdrant
`APP_QDRANT_COLLECTION`	`elearning_chunks`	Collection des passages indexés
`APP_EMBEDDING_BASE_URL`	vide	Vide : embeddings locaux (`sentence-transformers`). Renseigné : API compatible OpenAI
`APP_EMBEDDING_API_KEY`	clé du LLM	Clé du point d'accès d'embeddings
`APP_EMBEDDING_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	Modèle d'embeddings
`APP_EMBEDDING_DIMS`	`384`	Dimension des vecteurs ; doit correspondre au modèle
`APP_RAG_TOP_K`	`6`	Passages retenus par question
`APP_RAG_CHUNK_SIZE`	`800`	Taille d'un passage, en caractères
`APP_RAG_CHUNK_OVERLAP`	`120`	Recouvrement entre passages

Changer de modèle d'embeddings Les vecteurs existants ont la dimension de l'ancien modèle. Après un changement de APP_EMBEDDING_MODEL ou APP_EMBEDDING_DIMS, réindexez tout : e-learning-cli index-rag. Dans Docker, les modèles Hugging Face sont mis en cache dans le volume huggingface_cache, et les poids Whisper dans whisper_cache. Aucun poids n'est embarqué dans l'image : ils sont téléchargés au premier usage, puis conservés d'une recréation de conteneur à l'autre grâce à ces deux volumes.

File de jobs#

Variable	Défaut	Rôle
`APP_RABBITMQ_URL`	`amqp://guest:guest@localhost:5672/`	Broker
`APP_RABBITMQ_EXCHANGE`	`elearning_jobs`	Exchange de type direct
`APP_WORKER_PREFETCH`	`3`	Jobs traités en parallèle par processus worker

Sur une petite machine, APP_WORKER_PREFETCH=1 évite de lancer trois transcriptions Whisper en même temps.

Front#

Variable	Défaut	Rôle
`NEXT_PUBLIC_API_URL`	`http://localhost:8000`	URL de l'API vue par le navigateur ; intégrée au build (argument Docker)

Front et API sur le même site La session web tient dans un cookie SameSite=Lax posé par l'API. Ouvrez le front à une adresse listée dans APP_CORS_ORIGINS, et gardez front et API sur le même site : localhost:3000 et localhost:8000, ou learn.example.com et api.example.com. Ouvrir le front sur 127.0.0.1 alors que la liste contient localhost échoue avec une erreur CORS. Le cookie est marqué Secure dès que l'hôte de l'API n'est pas dans APP_INSECURE_COOKIE_HOSTS (localhost par défaut) : servez alors l'API en HTTPS, sinon le navigateur ignore le cookie et chaque appel renvoie 401. Sur un réseau local de confiance, vous pouvez à la place ajouter l'IP du serveur à cette liste.

L'application mobile a sa propre configuration (API_URL) : voir Application mobile.