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 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