Lancer le Backend
Ce fichier documente comment configurer et lancer le backend StageConnect en local.
Prérequis
| Outil | Version minimale | Notes |
|---|---|---|
| Python | 3.11+ | Obligatoire |
| Git | - | Pour cloner le repo |
| PostgreSQL | - | Fourni par Supabase (cloud) |
| Redis | - | Auto-hébergé sur VPS |
Installation
1. Cloner le repo
git clone https://github.com/AresGn/backend-sc.git
cd backend-sc
2. Créer l'environnement virtuel
python -m venv venv
source venv/bin/activate # Linux/macOS
# ou: venv\Scripts\activate # Windows
3. Installer les dépendances
pip install -r requirements.txt
Dépendances principales :
- FastAPI >= 0.109.0 — Framework web
- SQLAlchemy >= 2.0.25 — ORM pour les migrations
- Alembic >= 1.13.1 — Gestion des migrations
- Supabase >= 2.3.0 — Client DB
- Redis >= 5.0.0 — Cache
- Pydantic >= 2.5.3 — Validation des données
4. Configurer les variables d'environnement
cp .env.example .env
# Éditer .env avec vos valeurs
Le projet utilise python-dotenv pour charger les variables depuis .env.
5. Script de démarrage rapide
Le projet inclut un script start_server.sh :
./start_server.sh
Ce script :
- Active l'environnement virtuel
- Tue tout processus uvicorn existant (port 8000)
- Lance le serveur avec hot-reload
Sinon, lancer manuellement :
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Variables d'Environnement
| Variable | Description | Exemple |
|---|---|---|
ENVIRONMENT | Mode d'exécution (development/production) | development |
DEBUG | Mode debug | True |
SECRET_KEY | Clé de signature JWT | (générer avec openssl rand -hex 32) |
API_V1_STR | Préfixe des routes API | /api/v1 |
PROJECT_NAME | Nom du projet | StageConnect Backend |
Supabase
| Variable | Description |
|---|---|
SUPABASE_URL | URL du projet Supabase |
SUPABASE_ANON_KEY | Clé publique (anon) |
SUPABASE_SERVICE_ROLE_KEY | Clé service (admin, ne pas exposer) |
DATABASE_URL | URL PostgreSQL avec connection pooling |
DIRECT_URL | URL PostgreSQL directe (pour migrations) |
Redis
| Variable | Description |
|---|---|
REDIS_HOST | URL complète Redis |
REDIS_PORT | Port (6379 par défaut) |
REDIS_PASSWORD | Mot de passe Redis |
REDIS_DB | Numéro de DB (0 par défaut) |
Sécurité
| Variable | Description | Défaut recommandé |
|---|---|---|
ACCESS_TOKEN_EXPIRE_MINUTES | Durée access token | 15-30 minutes |
REFRESH_TOKEN_EXPIRE_DAYS | Durée refresh token | 7 jours |
ALGORITHM | Algo de signature JWT | HS256 |
:::note.security
La valeur actuelle dans .env est 720 (12h) pour éviter les reconnexions fréquentes pendant le développement. En production, privilégier 15-30 minutes pour limiter la fenêtre d'exposition en cas de token volé. Le refresh token (7 jours) permet de maintenir la session sans redemander le mot de passe.
:::
CORS
| Variable | Description |
|---|---|
BACKEND_CORS_ORIGINS | Liste des origines autorisées (JSON array) |
Storage
| Variable | Description | Défaut |
|---|---|---|
CLOUDINARY_CLOUD_NAME | Nom Cloudinary | - |
CLOUDINARY_API_KEY | Clé API Cloudinary | - |
CLOUDINARY_API_SECRET | Secret API Cloudinary | - |
UPLOAD_DIR | Répertoire d'upload local | ./uploads |
MAX_FILE_SIZE | Taille max fichier (octets) | 10485760 (10MB) |
Email
| Variable | Description |
|---|---|
SMTP_HOST | Serveur SMTP |
SMTP_PORT | Port SMTP (587 pour TLS) |
SMTP_USER | Utilisateur SMTP |
SMTP_PASSWORD | Mot de passe SMTP |
Vérifier que ça marche
API disponible
curl http://localhost:8000
Réponse attendue :
{
"message": "Welcome to StageConnect API",
"version": "1.0.0"
}
Health check
curl http://localhost:8000/health
Réponse attendue :
{
"status": "ok",
"environment": "development"
}
Redis health
curl http://localhost:8000/health/redis
Documentation API (Swagger)
Ouvrir http://localhost:8000/docs dans un navigateur.
Commandes Alembic
Le projet utilise Alembic pour les migrations :
# Voir l'état actuel
alembic current
# Appliquer les migrations
alembic upgrade head
# Créer une nouvelle migration
alembic revision --autogenerate -m "description"
# Rollback
alembic downgrade -1
Voir backend/migrations.md pour le workflow complet.
Problèmes Fréquents
"Module not found"
L'environnement virtuel n'est pas activé :
source venv/bin/activate
Erreur de connexion PostgreSQL
Vérifier que DATABASE_URL est correct dans .env et que le réseau peut accéder à Supabase.
Erreur de connexion Redis
Vérifier que REDIS_HOST est accessible. En local, Redis doit être joignable ou le cache sera désactivé (le backend fonctionne sans cache).
Port 8000 déjà utilisé
Le script start_server.sh tue automatiquement les processus uvicorn existants. Sinon :
pkill -f uvicorn
# puis relancer
uvicorn app.main:app --reload --port 8000
Production
En production, utiliser Gunicorn :
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker
Ou le script start-production.sh fourni.
Voir infrastructure/overview.md pour les détails de déploiement.