Hugging Face's logo

Spaces:
Ma-Ri-Ba-Ku
/
Picarones
Running

App Files Community
Picarones / docs /operations /rollback.md
Claude
chore(versioning): reposition project as 0.9.0 (pre-1.0)
416bee1 unverified
preview code
|
Raw
History Blame Contribute Delete
5.72 kB

Procédure de rollback

Guide opérationnel pour rétrograder une version Picarones en production institutionnelle.

Audience : équipe ops BnF / autres institutions.

Vue d'ensemble

Un rollback Picarones touche trois couches indépendantes :

  1. Code applicatif — l'image Docker / le wheel installé.
  2. Schéma SQLite des jobs — versionné dans la table schema_version.
  3. Configuration — variables d'environnement.

La règle d'or : rollback dans l'ordre inverse de la migration. Code → schéma → config.

1. Rollback du code applicatif

Cas A : déploiement Docker 

# Identifier la version actuelle
docker inspect picarones | grep Version

# Rollback vers la version précédente (ex : v0.10.0 → v0.9.0)
docker pull ghcr.io/maribakulj/picarones:v0.9.0
docker stop picarones
docker rm picarones
docker run --name picarones \
    -p 7860:7860 \
    --env-file /etc/picarones/.env \
    -v /var/lib/picarones/jobs.db:/app/jobs.db \
    ghcr.io/maribakulj/picarones:v0.9.0

# Vérifier
curl -fsS http://localhost:7860/health

Cas B : install pip 

# Lister les versions disponibles
pip index versions picarones

# Rollback
pip install --force-reinstall picarones==0.9.0

# Vérifier
picarones --version

Cas C : Kubernetes 

# Rollback la dernière révision du deployment
kubectl rollout undo deployment/picarones -n picarones-prod

# Ou cibler une révision spécifique
kubectl rollout history deployment/picarones -n picarones-prod
kubectl rollout undo deployment/picarones --to-revision=42

# Vérifier
kubectl rollout status deployment/picarones
kubectl get pods -n picarones-prod

2. Rollback du schéma SQLite

JobStore (picarones/adapters/storage/job_store.py) versionne son schéma dans la table schema_version. Si le rollback du code nécessite de revenir à un schéma antérieur :

Cas simple : downgrade non destructif

Si la migration N→N+1 a uniquement ajouté des colonnes / tables (jamais supprimé), le code de la version cible lit un schéma plus récent sans plantage — les nouvelles colonnes sont simplement ignorées.

Aucune action requise.

Cas complexe : downgrade destructif

Si la migration a renommé/supprimé des colonnes, le code de la version cible peut lever des sqlite3.OperationalError.

Procédure :

  1. Stopper Picarones.

  2. Sauvegarder la DB :

    cp /var/lib/picarones/jobs.db \
   /var/lib/picarones/jobs.db.before-rollback-$(date +%Y%m%d-%H%M%S)

  3. Restaurer un dump pré-migration depuis la sauvegarde quotidienne :

    # Localisation typique de la backup
ls /var/backups/picarones/

# Restaurer la veille de la migration
sqlite3 /var/lib/picarones/jobs.db ".restore /var/backups/picarones/jobs.db.YYYY-MM-DD"

  4. Forcer le schema_version à la valeur attendue par le code de la version cible (si nécessaire) :

    sqlite3 /var/lib/picarones/jobs.db
sqlite> UPDATE schema_version SET version = 1;
sqlite> .quit

  5. Redémarrer Picarones à la version cible.

  6. Vérifier que les jobs anciens sont lisibles via GET /api/jobs.

Pas de backup ?

Le code Picarones (depuis 0.9.0) a un mode "lecture seule défensive" : si le schema_version est plus récent que celui attendu, le code log un warning explicite et tente de continuer. En cas d'incident, les jobs nouveaux fonctionnent ; les jobs anciens (avec des champs nouveaux) peuvent apparaître tronqués mais ne crashent pas.

3. Rollback de la configuration

Les variables d'environnement sont versionnées hors du code (secret manager + .env non committé). Pour rollback :

# Si la config a été modifiée en même temps que la release :
# remettre le snapshot précédent du .env

cp /etc/picarones/.env.before-deploy /etc/picarones/.env

# Recharger
docker compose restart  # ou systemctl restart picarones

4. Vérifications post-rollback

Checklist obligatoire :

  • curl /health retourne 200.
  • curl /version retourne la version cible.
  • GET /api/jobs liste les jobs sans erreur.
  • Les logs ne montrent pas de sqlite3.OperationalError ou de KeyError sur des colonnes manquantes.
  • Soumission d'un nouveau benchmark via UI fonctionne.
  • CSRF token (si mode institutionnel) : GET /api/csrf/token retourne 200, et un POST avec ce token passe le middleware.
  • Logs en JSON (si PICARONES_LOG_FORMAT=json) parsables par l'ingester.

5. Cas d'urgence : rollback total

Si le déploiement est compromis (sécurité, données corrompues) :

# 1. Couper le trafic au reverse-proxy
nginx -s stop  # ou : kubectl scale deployment/picarones --replicas=0

# 2. Snapshot disque complet
tar czf /var/backups/picarones-emergency-$(date +%s).tar.gz \
    /var/lib/picarones/

# 3. Restaurer la dernière version stable connue + DB de la veille
# (suivre §1 Cas A/B/C + §2 ci-dessus)

# 4. Notifier les utilisateurs (SSO bandeau, email)

6. Pas de rollback automatique

Picarones n'inclut pas de rollback automatique sur erreur post-déploiement. La discipline est :

  • Déployer en horaire de faible trafic.
  • Surveiller les logs pendant 30 min après déploiement.
  • Avoir la procédure ci-dessus prête (testée régulièrement en préprod).
  • En cas de doute, rollback rapide vaut mieux que diagnostic prolongé.

Voir aussi