Vérification et dépannage

Effectuez ces vérifications après une installation ou une mise à jour. Les commandes docker compose s'exécutent depuis le répertoire generated_files/ :

cd ./app/avatar/generated_files

Vérification rapide

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

provision-admin crée une clé API administrateur pour le compte akadmin, dans generated_files/.secrets/avatar_api_key. Il suffit de l'exécuter une seule fois. verify contrôle ensuite l'API avec cette clé et envoie un email de test via Authentik.

Vérifications manuelles

Conteneurs

docker compose ps

Chaque service doit être running ou healthy, et aucun ne doit redémarrer en boucle. Les services sont api, web, nginx, db, dask-scheduler, dask-worker, master, volume, filer, s3, authentik_server et authentik_worker. init-db, init-storage et authentik_init_db s'arrêtent une fois leur travail terminé.

Santé de l'API

curl -k https://<your-domain>/api/health

Cette commande retourne {"message":"ok"} et ne nécessite aucune authentification. Pour un contrôle complet de la configuration, appelez /health/config-full-check avec la clé API administrateur :

curl -s -k https://<your-domain>/api/health/config-full-check \
  -H "Authorization: api-key-v1 $(cat .secrets/avatar_api_key)" | python3 -m json.tool

Il contrôle l'environnement et les secrets, la base de données et les migrations en attente, l'accès au stockage, les emails, la page de connexion web, les workers et la télémétrie. Il retourne 200 lorsque tout réussit, 207 en cas d'avertissements et 500 lorsqu'une vérification échoue. Le corps de la réponse détaille chaque vérification.

Emails

Les emails sont envoyés par Authentik :

docker compose exec authentik_worker ak test_email you@company.com

Chiffrement du stockage

Vérifiez que SeaweedFS peut lire et écrire dans les buckets chiffrés :

docker compose logs -t s3 --tail=100

Des erreurs SSE-S3 signifient que .secrets/storage_encryption_key ne correspond pas à la clé détenue par le filer. Comparez-les :

docker compose exec master weed shell
> fs.cat /etc/s3/sse_kek

Si elles diffèrent, remettez la valeur du filer dans votre configuration et redémarrez la stack. Ne conservez jamais une nouvelle clé : tous les objets stockés deviendraient illisibles. Consultez la documentation SeaweedFS.

Connexion

1. Ouvrez https://<your-domain>/.
2. Connectez-vous avec un compte créé par tasks create-users, ou en tant qu'akadmin avec les AUTHENTIK_BOOTSTRAP_EMAIL et AUTHENTIK_BOOTSTRAP_PASSWORD du fichier .env.
3. Vérifiez que vous revenez dans l'interface Avatar et qu'elle affiche la version attendue.

Le serveur n'a pas de navigateur

Redirigez le port HTTPS via SSH depuis votre poste de travail :

ssh -L 8443:localhost:443 user@server

Faites pointer le domaine vers votre machine en ajoutant 127.0.0.1 <your-domain> à votre fichier /etc/hosts local, puis ouvrez https://<your-domain>:8443/.

Test d'avatarisation

Téléversez un petit jeu de données, lancez une avatarisation et téléchargez le résultat. C'est la seule vérification qui sollicite les workers et le stockage de bout en bout.

Si une vérification échoue

Symptôme	Correctif
verify signale "API key not found"	Exécutez d'abord tasks provision-admin.
Les conteneurs démarrent mais ne parviennent pas à communiquer entre eux	Docker utilise un proxy HTTP. Ajoutez le paramètre noProxy, puis recréez les conteneurs.
install s'arrête : "Volume 'avatar_postgres_data' already exists"	Le serveur contient les données d'un déploiement précédent. Utilisez update sur le répertoire de ce déploiement pour les conserver, ou uninstall pour les supprimer.
install ou update indique que le répertoire est "pre-versioned"	Effectuez la Migration héritée.
update s'arrête : "Apply is blocked until conflicts are resolved"	Quelqu'un a modifié generated_files/. Reportez ces modifications dans un fichier de configuration, puis acceptez le nouveau rendu.
La récupération des images échoue (unauthorized, denied)	Relancez la commande docker login quay.io qu'Octopize vous a transmise.
L'API ne devient jamais saine après une mise à jour	Consultez docker compose logs api : un échec de migration de base de données y est signalé. Voir Retour à la version précédente.
Les écritures dans le stockage échouent, erreurs SSE-S3 dans les logs s3	La clé de chiffrement du stockage a changé. Voir Chiffrement du stockage.
Aucun email n'arrive	Vérifiez les paramètres SMTP et que le serveur peut joindre votre serveur SMTP, puis relancez ak test_email.
Les modifications SSO ne sont pas prises en compte après update	Exécutez octopize-deploy-tool tasks reconcile-blueprint --app-root ./app/avatar.
Vous n'avez plus accès à Authentik	Voir Récupérer l'accès administrateur.
Le disque est plein	Supprimez les images inutilisées avec docker image prune -a, ou déplacez le stockage de Docker.

Ajoutez --verbosity 2 à n'importe quelle commande de l'outil de déploiement pour obtenir une sortie détaillée.

Repartir de zéro

Utilisez octopize-deploy-tool uninstall, qui demande une confirmation et supprime ensemble les conteneurs, les volumes et les fichiers de déploiement. Cette commande supprime tous les jeux de données et tous les comptes utilisateurs. N'exécutez pas docker compose down --volumes à la main : cette commande supprime la base de données mais laisse les fichiers de déploiement en place.

Collecter les informations de diagnostic

Avant de contacter le support Octopize, collectez :

docker compose ps > diagnostics-ps.txt
docker compose logs --tail=20000 > diagnostics-logs.txt 2>&1
cp .env diagnostics-env.txt

attention

Retirez les mots de passe, jetons et secrets de ces fichiers avant de les partager.

Envoyez-les à support@octopize.io accompagnés d'une description du problème.