Mise à jour et retour arrière

Chaque version d'octopize-deploy-tool embarque les templates et les versions d'images d'une version d'Avatar. Mettre à jour Avatar revient donc à mettre à jour l'outil, puis à le laisser régénérer et redémarrer la stack.

Déploiement configuré à la main, ou antérieur à Authentik ?

Si votre répertoire de déploiement contient .env et .secrets/ à sa racine et aucun .deployment_states/, effectuez d'abord la Migration héritée, une opération ponctuelle.

Avant la mise à jour

• Lisez les notes de version de la version cible.
• Planifiez une fenêtre de maintenance : la stack redémarre, ce qui prend généralement 5 à 15 minutes, auxquelles s'ajoute la durée des migrations de base de données.
• Vérifiez que vous disposez d'environ 6 Go d'espace disque libre pour les nouvelles images.
• Sauvegardez les bases de données et le répertoire de déploiement.

Sauvegarde

Sauvegardez deux choses : les deux bases de données (celle d'Avatar et celle d'Authentik) et l'intégralité du répertoire de déploiement, qui contient les secrets, dont la clé de chiffrement du stockage. Les fichiers de sauvegarde sont écrits à côté du répertoire de déploiement :

cd ./app/avatar/generated_files
STAMP=$(date +%Y%m%d-%H%M%S)
DB_ADMIN=$(cat .secrets/db_admin_user)

# Les deux bases, en SQL qui supprime puis recrée leurs objets à la restauration
for DB in $(cat .secrets/db_name) $(cat .secrets/authentik_database_name); do
  docker compose exec -T db pg_dump -U "$DB_ADMIN" --clean --if-exists -d "$DB" \
    > "../../avatar-backup-$STAMP-$DB.sql"
done

# Le répertoire de déploiement : configuration, toutes les versions rendues et les secrets
tar czf "../../avatar-backup-$STAMP-app.tar.gz" -C ../.. avatar

Conservez ces fichiers en lieu sûr : ils contiennent tous les identifiants du déploiement.

Les jeux de données stockés dans SeaweedFS sont temporaires et expirent d'eux-mêmes ; ils ne font donc pas partie de la sauvegarde. Les utilisateurs téléchargent leurs résultats.

En production, planifiez la sauvegarde des bases de données, conservez au moins 30 jours de sauvegardes et testez régulièrement une restauration.

Mise à jour

1. Mettre à jour l'outil de déploiement

pip install --upgrade octopize-deploy-tool

Si vous exécutez l'outil depuis Docker, récupérez plutôt quay.io/octopize/deploy-tool:latest.

2. Régénérer la configuration

octopize-deploy-tool update --app-root ./app/avatar

Vos valeurs sont reprises. L'outil rend les nouveaux templates dans un nouvel emplacement de version, affiche la différence, en commençant par les versions de services qui changent, puis l'applique. Il ne redémarre encore rien.

Les versions de l'outil de déploiement postérieures à 3.5.1 exigent le nouveau secret seaweedfs_admin_password. update le génère. Pour fournir votre propre valeur, voir Mot de passe d'administration SeaweedFS.

update se termine en listant les versions du client Python compatibles avec la nouvelle API. Si le client de vos utilisateurs doit être mis à jour, prévenez-les avant leur prochain traitement.

3. Redémarrer la stack

octopize-deploy-tool start --app-root ./app/avatar

Cette commande récupère les nouvelles images, recrée les conteneurs et applique de nouveau le blueprint Authentik. L'API exécute les migrations de base de données à son démarrage.

4. Vérifier

octopize-deploy-tool verify --app-root ./app/avatar --test-email you@company.com

Connectez-vous ensuite via le client web et lancez une petite avatarisation. En cas d'échec, consultez Vérification et dépannage.

Authentik avance d'une ligne de version par mise à jour

Authentik met à jour sa base de données une ligne de version à la fois (2026.2, puis 2026.5, puis 2026.8), et à partir de 2026.8 il refuse de démarrer sur une base de données qui en a sauté une. À partir de l'outil de déploiement 3.6.0, update fait avancer Authentik d'au plus une ligne de version depuis la version qu'a atteinte votre base de données Authentik. Une nouvelle installation obtient directement la dernière version d'Authentik.

Un déploiement sur un Authentik antérieur à 2026.5 nécessite donc une mise à jour par ligne de version. Par exemple, depuis 2026.2 :

1. Le premier update donne Authentik 2026.5.7. Exécutez start et verify comme ci-dessus. Ils enregistrent qu'Authentik exécute 2026.5.7.
2. Recommencez la mise à jour. Cet update donne Authentik 2026.8.

La différence qu'affiche update indique la version d'Authentik choisie. verify vérifie aussi qu'Authentik exécute la version du déploiement, et échoue sinon.

Ne sautez pas de ligne de version

Si vous fixez AVATAR_AUTHENTIK_VERSION dans votre configuration, gardez-la au plus une ligne de version au-delà de celle qu'exécute Authentik. Sinon, Authentik s'arrête au démarrage avec Major version skips are not allowed. update vous avertit et indique la version à utiliser. Authentik ne peut pas revenir en arrière sur sa base de données : sauvegardez-la avant chaque mise à jour.

Retour à la version précédente

Revenez à la version précédente si l'API ne devient pas saine, si une migration échoue, ou si la connexion, l'avatarisation ou le stockage sont défaillants et ne peuvent pas être corrigés pendant la fenêtre de maintenance. Commencez par collecter les informations de diagnostic, afin que le problème puisse être analysé par la suite.

Les migrations de base de données ne sont pas réversibles : une base migrée vers l'avant ne fonctionne pas avec la version précédente de l'API. Un retour à la version précédente restaure donc les bases de données depuis la sauvegarde.

# 1. Arrêter la stack
octopize-deploy-tool stop --app-root ./app/avatar

# 2. Remettre en place la version rendue précédente (lister les emplacements avec : ls ./app/avatar/.deployment_states)
octopize-deploy-tool apply --app-root ./app/avatar --version v1

# 3. Restaurer les deux bases de données
cd ./app/avatar/generated_files
docker compose up -d db
DB_ADMIN=$(cat .secrets/db_admin_user)
for DB in $(cat .secrets/db_name) $(cat .secrets/authentik_database_name); do
  docker compose exec -T db psql -U "$DB_ADMIN" -d "$DB" < "../../avatar-backup-<STAMP>-$DB.sql"
done
cd -

# 4. Démarrer la version précédente
octopize-deploy-tool start --app-root ./app/avatar

Remplacez v1 par l'emplacement déployé avant la mise à jour, et <STAMP> par l'horodatage de votre sauvegarde. Vérifiez ensuite le déploiement.

Si le répertoire de déploiement lui-même est endommagé, restaurez-le d'abord depuis l'archive tar.gz.