Installation

Prérequis#

• Docker et Docker Compose.
• Git avec Git LFS : images, vidéo de démonstration et polices sont stockées ainsi.
• Un accès Internet au premier démarrage : images Docker, et modèle d'embeddings téléchargé depuis Hugging Face (mis en cache ensuite).
• Hors Docker uniquement : Node 22+, Python 3.14+, uv et ffmpeg.

Aucun modèle de langage n'est requis pour démarrer. Catalogue, lecteur, progression, notes, documents et studio fonctionnent sans. Un point d'accès compatible OpenAI (LM Studio, Ollama, vLLM, ou un fournisseur distant) active ensuite résumés et assistant ; voir Brancher un modèle.

Ressources#

Ordres de grandeur mesurés sur une instance Docker avec le modèle d'embeddings par défaut, sans LLM local :

Une machine avec 8 Go de mémoire fait tourner la pile et une transcription à la fois. Un LLM local (LM Studio, Ollama) s'ajoute à ce budget, souvent de plusieurs Go selon le modèle.

Avec Docker Compose#

git lfs install                  # une fois par machine, avant le clone
git clone https://github.com/EdwinAlkins/e-learning.git
cd e-learning
cp .env.template .env

Dans .env, les valeurs à regarder en premier :

docker compose up -d --build     # à la racine du dépôt
docker compose ps

Au démarrage, le service migrate applique les migrations Alembic puis s'arrête ; l'API et le worker attendent qu'il ait réussi.

Ouvrez http://localhost:3000 et connectez-vous avec APP_FIRST_ADMIN_EMAIL et APP_FIRST_ADMIN_PASSWORD. Studio permet ensuite de créer une première formation, et Studio → Comptes d'ouvrir des accès aux apprenants.

Si l'API redémarre en boucle, docker compose logs api indique la variable à corriger : clé ou mot de passe d'exemple, ou "*" dans APP_CORS_ORIGINS.

Importer des vidéos existantes#

Rangez les médias sous VIDEOS_HOST_PATH en Formation/Chapitre/fichier (détails dans Studio et catalogue), puis réconciliez :

docker compose exec api e-learning-cli reconcile
docker compose exec api e-learning-cli list-videos

Ou, pour que la réconciliation tourne à chaque démarrage de l'API : APP_RECONCILE_ON_STARTUP=true.

Hors Docker#

Utile pour développer. Les services d'infrastructure restent dans Docker :

docker compose up -d postgres rabbitmq qdrant

# API
cd e-learning-api
cp .env.template .env           # URLs en localhost ; APP_DEBUG=true pour le dev
uv sync --group ai --group dev
uv run alembic upgrade head
uv run e-learning-api           # http://localhost:8000

# Worker, dans un second terminal
uv run e-learning-worker

# Front, dans un troisième
cd ../e-learning-front
cp .env.template .env.local
npm ci
npm run dev                     # http://localhost:3000

Avec APP_DEBUG=true, l'API accepte les secrets d'exemple (avec un avertissement) et sert la documentation OpenAPI sur /api-docs. Le compte admin d'exemple est alors admin@example.com / changethis.

Exposer l'instance#

Chaque page et chaque route de l'API exigent une connexion, et le studio est réservé aux administrateurs. Avant une exposition sur Internet, trois points restent à régler.

• HTTPS obligatoire. Le cookie de session est marqué Secure dès que l'API n'est pas servie sur localhost : en HTTP, le navigateur le refuse et la connexion web échoue. Les mots de passe transitent aussi dans la requête.
• Secrets. APP_SECRET_KEY d'au moins 32 caractères, mot de passe admin changé, APP_DEBUG=false.
• Ports d'infrastructure. Le compose publie aussi PostgreSQL, RabbitMQ (identifiants guest par défaut) et Qdrant sur toutes les interfaces. Retirez ces ports ou liez-les à la boucle locale, par exemple dans un docker-compose.override.yml (Compose 2.24+ pour !override) :

services:
  postgres:
    ports: !override
      - "127.0.0.1:${POSTGRES_PORT}:5432"

Un schéma simple : un seul domaine, le front à la racine et l'API sous /api. Front et API restent ainsi sur le même site, ce qu'exige le cookie de session. Exemple avec Caddy, qui obtient le certificat HTTPS tout seul :

learn.example.com {
	handle_path /api/* {
		reverse_proxy 127.0.0.1:8000
	}
	handle {
		reverse_proxy 127.0.0.1:3000
	}
}

Et dans .env, avant de reconstruire le front :

NEXT_PUBLIC_API_URL=https://learn.example.com/api
APP_CORS_ORIGINS=["https://learn.example.com"]
APP_DEBUG=false

Ajouter une protection en amont#

Les comptes intégrés suffisent pour la plupart des usages. Une couche en amont réduit encore la surface exposée :

L'application mobile appelle l'API directement et ne sait pas passer une page de connexion tierce : avec un proxy SSO, elle ne fonctionne qu'à travers un VPN. Cladèse ne se connecte pas lui-même à un fournisseur d'identité (SSO, OIDC).

Mettre à jour#

./scripts/backup.sh             # d'abord
git pull
docker compose up -d --build    # migrate applique les nouvelles migrations

Depuis une version sans comptes, lisez d'abord l'avertissement sur la migration 007 : elle supprime les progressions et notes des anciens identifiants anonymes.

Vérifier l'état : GET /health répond si le processus tourne, GET /ready vérifie aussi la connexion à PostgreSQL.