open-school/DEPLOYMENT_NOTES.md

Deployment Notes

Stack Reelle

Le deploiement utilise sur le serveur n'est pas celui d'un docker-compose.yml versionne dans ce repo.

La stack reelle comprend notamment:

• tutor-backend
• tutor-frontend
• tutor-postgres
• tutor-redis
• nginx

Routage Nginx

Pour prof.open-squared.tech, la conf partagee pendant la session est:

• location /api/ -> http://tutor-backend:8000/
• location / -> http://tutor-frontend:3000/

Consequence:

• le frontend doit appeler l'API via /api
• nginx supprime le prefixe /api/ avant d'envoyer au backend
• GET /api/students devient GET /students cote FastAPI

Incidents Rencontres

1. Bouton "Creer un eleve" casse

Cause:

• le frontend recevait une page HTML d'erreur au lieu d'un JSON
• JSON.parse echouait

Diagnostic final:

• nginx renvoyait 502 Bad Gateway
• tutor-backend etait indisponible

2. Backend qui ne demarre plus

Cause:

• ajout de la route /transcribe
• FastAPI exige python-multipart pour les uploads multipart/form-data

Resolution:

• ajouter python-multipart dans backend/requirements.txt
• rebuild du conteneur backend

3. Micro automatique instable dans Firefox

Cause:

• la premiere approche de detection audio etait trop fragile dans Firefox

Resolution:

• simplification et renforcement de la capture audio
• relance automatique du segment d'ecoute apres la reponse du prof

Commandes Utiles Cote Serveur

Quelques commandes utiles deja identifiees:

docker logs tutor-backend
docker compose up -d --build tutor-backend
curl -i https://prof.open-squared.tech/api/health
curl -i https://prof.open-squared.tech/api/students

Ameliorations Possibles

• Servir le frontend compile plutot que Vite en production
• Supprimer le bruit HMR/WebSocket en production
• Ajouter une page ou section admin de diagnostic micro/API
• Documenter la stack serveur hors repo dans un espace partage dedie