Déploiement
Guide de déploiement en production pour SPARC 2.x (paquet 2.0.0)
Prérequis Système
| Composant | Version minimale | Notes |
|---|---|---|
| Docker | 24.x | docker --version |
| Docker Compose | 2.20 | docker compose version |
| RAM disponible | 4 GB | 8 GB recommandé pour BoTorch |
| CPU | 4 cœurs | Workers Celery |
| Espace disque | 10 GB | Images + données + archives |
Checklist de Sécurité
Variables d'Environnement
Terminal
cp .env.example .env
Obligatoire : Remplacer les valeurs par défaut dans
.env
| Variable | Action requise |
|---|---|
SESAME_WEB_SECRET |
Générer avec python -c "import secrets; print(secrets.token_hex(32))" |
MATERIALS_PROJECT_API_KEY |
Obtenir sur next-gen.materialsproject.org/api ou laisser vide. Alias : MP_API_KEY, MAPI_KEY |
SPARC_RETENTION_DAYS |
Ajuster selon les besoins (défaut : 90) |
Important : Ne jamais committer
.env — il est dans .gitignore.
Secrets Flask
Terminal
# Vérifier que la valeur est bien un token aléatoire (pas "changeme")
grep SESAME_WEB_SECRET .env
Base de Données
La base SQLite est dans un volume Docker nommé. En production :
Terminal
# Sauvegarder avant mise à jour
docker compose exec web sqlite3 /app/data/sparc.db ".backup /app/data/sparc.backup.db"
Construction et Démarrage
Terminal
# Construction des images
docker compose build
# Premier démarrage (télécharge PyTorch CPU, Sesame, etc.)
docker compose up -d
# Vérifier les logs
docker compose logs -f
# Vérifier la santé des services
docker compose ps
Après une mise à jour de
requirements.txt (ex. ajout de mp-api), toujours relancer docker compose build --no-cache puis docker compose up -d sans quoi le conteneur continue d'utiliser l'ancienne image.
Déploiement sans Docker (Bare Metal / VM)
Pour un hôte Linux sans Docker — ex. VM institutionnelle, HPC, Raspberry Pi puissant. Testé avec Python 3.10 / 3.11 / 3.12.
Dépendances par Mode d'Utilisation
| Mode | Dépendances supplémentaires | Commande |
|---|---|---|
| Interface web | *(incluses dans requirements.txt)* |
— |
| CLI interactif | rich, questionary, prompt_toolkit |
pip install rich questionary prompt_toolkit |
| CLI batch | *(incluses dans requirements.txt)* |
— |
| Optimiseur avancé | botorch, torch |
pip install botorch torch |
| Génération de plots on-the-fly | matplotlib |
pip install matplotlib |
matplotlib est optionnel pour le serveur web. Dans l'état documenté 2026, l'application Flask démarre sans erreur même si matplotlib n'est pas installé. La génération de graphiques PNG via l'API sera désactivée, mais toutes les autres fonctionnalités restent opérationnelles.
Installation Bare Metal
Terminal
# 1. Paquets système (Debian/Ubuntu — adaptez pour RHEL/Arch)
sudo apt update && sudo apt install -y \
python3 python3-venv python3-pip \
git build-essential libhdf5-dev libopenblas-dev redis-server
# 2. Cloner et installer
git clone https://github.com/Quantum-ARISE-Acad/SPARC.git
cd sparc
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install git+https://github.com/usnistgov/sesame.git
pip install -r requirements.txt
# CLI interactif — dépendances requises
pip install rich questionary prompt_toolkit
# 3. Configuration
cp .env.example .env
nano .env # définir SESAME_WEB_SECRET, MATERIALS_PROJECT_API_KEY, etc.
# 4. Lancement avec Gunicorn + Celery (production)
gunicorn -w 4 -b 0.0.0.0:5000 "web.app:app" --daemon
celery -A web.tasks worker --loglevel=info --detach
celery -A web.tasks beat --loglevel=info --detach
# 5. Service systemd (recommandé)
sudo systemctl enable --now sparc-web sparc-worker sparc-beat
Avantages : accès direct aux logs et itération Python plus simple.
Inconvénients : Isolation faible, dépendances Python/numpy pinnées à l'hôte, sauvegardes manuelles de
Inconvénients : Isolation faible, dépendances Python/numpy pinnées à l'hôte, sauvegardes manuelles de
web/simulations.db.
Tests de Fumée Post-Déploiement
Terminal
# 1. Interface web accessible
curl -f http://localhost:5000/ || echo "KO"
# 2. API health
curl -f http://localhost:5000/api/health || echo "KO"
# 3. Swagger disponible
curl -f http://localhost:5000/api/docs/ || echo "Swagger KO"
# 4. Redis opérationnel
docker compose exec redis redis-cli ping
# 5. Celery worker actif
docker compose exec worker celery -A workers.celery_app inspect ping
# 6. Flower (supervision)
curl -f http://localhost:5555 || echo "Flower KO"
# 7. CLI interactif & version SPARC (ou via conteneur docker compose run --rm cli sparc --version)
sparc --version
sparc ui
# 8. CLI batch — toutes les commandes disponibles
sparc --help
Configuration du Reverse Proxy (Production)
En production, placez nginx ou Caddy devant le port Flask.
Nginx Minimal
nginx.conf
server {
listen 80;
server_name your.domain.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# SSE : désactiver le buffering pour la progression temps réel
proxy_buffering off;
proxy_cache off;
}
}
Important :
proxy_buffering off est indispensable pour que les Server-Sent Events (progression de simulation) fonctionnent.
Sauvegarde et Restauration
Sauvegarde Complète
backup.sh
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M)
# Base de données
docker compose exec web sqlite3 /app/data/sparc.db ".dump" > backup_${DATE}.sql
# Volume résultats
docker run --rm -v sparc_data:/data -v $(pwd):/backup \
alpine tar czf /backup/sparc_data_${DATE}.tar.gz -C / data
Restauration
restore.sh
# Arrêter les services
docker compose stop
# Restaurer les données
docker run --rm -v sparc_data:/data -v $(pwd):/backup \
alpine sh -c "cd / && tar xzf /backup/sparc_data_.tar.gz"
# Redémarrer
docker compose up -d
Variables d'Environnement Complètes
| Variable | Défaut | Description |
|---|---|---|
SESAME_WEB_SECRET |
*(à définir)* | Clé secrète Flask (sessions, CSRF) |
SPARC_WEB_PORT |
5000 |
Port HTTP Flask |
SESAME_WEB_HOST |
0.0.0.0 |
Adresse d'écoute |
SESAME_WEB_DEBUG |
0 |
Mode debug Flask (ne pas activer en prod) |
SPARC_DB_PATH |
/app/data/sparc.db |
Chemin base SQLite |
REDIS_URL |
redis://redis:6379/0 |
URL broker Redis |
CELERY_CONCURRENCY |
2 |
Workers Celery parallèles |
SPARC_FLOWER_PORT |
5555 |
Port supervision Celery Flower |
MATERIALS_PROJECT_API_KEY |
*(optionnel)* | Clé API Materials Project (alias : MP_API_KEY, MAPI_KEY) |
SPARC_LLM_PROVIDER |
ollama |
ollama ou anthropic |
SPARC_LLM_MODEL |
llama3.2 |
Modèle Ollama à utiliser |
OLLAMA_BASE_URL |
http://ollama:11434 |
URL serveur Ollama |
ANTHROPIC_API_KEY |
*(optionnel)* | Clé API Anthropic (si provider=anthropic) |
SPARC_RETENTION_DAYS |
90 |
Rétention des simulations archivées |
Mise à Jour
Terminal
# Tirer les nouvelles images
git pull origin main
# Reconstruire
docker compose build
# Redémarrer sans temps d'arrêt (rolling restart)
docker compose up -d --no-deps --build web worker beat
# Vérifier les migrations de base de données si nécessaire
docker compose exec web python -c "from web.database import init_db; init_db()"
Surveillance
- Flower :
http://localhost:5555— files Celery, workers actifs, tâches en cours - Logs :
docker compose logs -f [web|worker|beat] - Statistiques globales :
http://localhost:5000/statistics - Redis :
docker compose exec redis redis-cli info stats
Problèmes Courants
| Symptôme | Cause probable | Solution |
|---|---|---|
500 Internal Server Error |
SESAME_WEB_SECRET manquant |
Définir la variable dans .env |
| Simulation bloquée à 0% | Redis ou worker non démarré | docker compose up -d redis worker |
| SSE ne s'actualise pas | nginx bufferise les réponses | Ajouter proxy_buffering off |
| Worker OOM | PyTorch ou BoTorch trop gourmand | Augmenter RAM ou réduire CELERY_CONCURRENCY |
| Modèle Ollama absent | Pas de pull effectué | docker compose exec ollama ollama pull llama3.2 |
| Surrogate "permission denied" | outputs/ non inscriptible |
Automatiquement redirigé vers ~/.sparc/surrogates/ |
| PDF introuvable | Sauvegardé dans le CWD | Chercher dans outputs/pdf/ ou ~/.sparc/reports/ |
| Materials Project échoue | Clé API absente | Définir MATERIALS_PROJECT_API_KEY (ou MP_API_KEY) dans .env |
| Plots PNG absents via l'API | matplotlib non installé |
pip install matplotlib (optionnel — le serveur démarre sans lui dans l'état documenté 2026) |
CLI interactif : ModuleNotFoundError: rich |
Dépendance absente | pip install rich questionary prompt_toolkit |