Dépannage¶
Problèmes courants et leur résolution. Commencez par consulter les logs du backend :
Problèmes de démarrage¶
Le backend échoue à démarrer — JWT_SECRET_KEY manquant¶
Symptôme : le conteneur se termine immédiatement avec :
Cause : la variable JWT_SECRET_KEY est vide ou absente de backend.env.
Correction :
# Générer une clé forte
openssl rand -hex 32
# Ajouter à backend.env :
JWT_SECRET_KEY=<valeur-generee>
docker compose up -d backend-api
ClamAV met plus de 60 secondes à démarrer¶
Symptôme : l'endpoint de santé renvoie "clamav": {"ok": false} pendant
jusqu'à 2 minutes après le démarrage.
Cause : ClamAV charge ~800 Mo de signatures en mémoire au premier démarrage. C'est un comportement normal.
Correction : patientez. Les démarrages suivants sont plus rapides car la
base est mise en cache dans le volume repos/clamav-db/. Si le problème
persiste après 5 minutes, vérifiez :
Erreur de base de données : connection refused / password authentication failed¶
Symptôme :
sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server at "db" ... refused
sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) FATAL: password authentication failed for user "repod"
Cause : backend-api a démarré avant que PostgreSQL n'ait fini son
initialisation, ou DATABASE_URL (dans backend.env) ne correspond pas à
POSTGRES_PASSWORD (dans .env) utilisé pour initialiser le conteneur db.
Correction :
# Vérifier que le conteneur db est en bonne santé
docker compose ps db
docker compose logs db --tail=50
# Vérifier que DATABASE_URL correspond aux identifiants avec lesquels le
# volume db a été initialisé
docker exec backend-api env | grep DATABASE_URL
docker exec repod-db env | grep POSTGRES_PASSWORD
# Redémarrer backend-api une fois db en bonne santé
docker compose restart backend-api
Changer POSTGRES_PASSWORD après le premier démarrage n'a aucun effet
PostgreSQL n'applique POSTGRES_PASSWORD que lors de l'initialisation
d'un volume postgres_data vide. Si vous le changez ensuite, mettez
également à jour le mot de passe à l'intérieur de PostgreSQL
(ALTER USER repod WITH PASSWORD '...'), sinon DATABASE_URL dans
backend.env cessera de correspondre.
Échecs d'upload¶
« Erreur serveur » lors de l'upload d'un paquet¶
Symptôme : l'interface web affiche « Erreur serveur » après la sélection d'un fichier.
Cause : le client_max_body_size de Nginx est inférieur à la taille du
fichier. La valeur par défaut dans certaines configurations est 1 Mo, ce qui
bloque tout upload de paquet réel.
Diagnostic :
docker compose logs frontend-ui | grep 413
# Ou vérifier dans l'onglet Réseau du navigateur — rechercher un HTTP 413 sur
# la requête d'upload
Correction : le nginx.conf dans frontend/nginx.conf doit contenir :
Upload rejeté — « Erreur réseau : NetworkError »¶
Symptôme : l'upload échoue avec une erreur réseau, avant même que le serveur ne reçoive le fichier.
Cause (la plus fréquente) : le frontend a été construit avec
REACT_APP_API_URL=http://localhost:8000, ce qui pousse le navigateur à
essayer d'atteindre localhost:8000 sur la machine cliente plutôt que sur
le serveur.
Diagnostic :
Correction : définir la bonne URL dans .env et reconstruire :
# .env
REACT_APP_API_URL=http://192.168.1.100:8000 # ou l'adresse réelle de votre serveur
docker compose build frontend-ui
docker compose up -d frontend-ui
Paquet bloqué en pending_review¶
Symptôme : un paquet a été uploadé avec succès mais n'apparaît pas dans
le dépôt APT/RPM. L'interface web affiche Status: pending_review.
Cause : le scan CVE a trouvé des vulnérabilités correspondant à la
politique review configurée. Le paquet est stocké mais non publié tant
qu'il n'est pas approuvé.
Correction : 1. Ouvrir Sécurité → File de revue dans l'interface web 2. Examiner les détections CVE pour le paquet 3. Cliquer sur Approuver pour publier, ou Rejeter pour retirer de la file
Ou bien via l'API :
curl -X POST http://localhost:8000/api/v1/security/packages/mypackage/1.0.0/decide \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"decision":"approve","justification":"Vulnerability does not apply to our use case"}'
Problèmes clients APT¶
apt update échoue — NO_PUBKEY¶
Symptôme :
W: GPG error: http://repod.example.com:80 jammy InRelease: The following signatures
couldn't be verified because the public key is not available: NO_PUBKEY ABCD1234...
Cause : la clé publique GPG du dépôt n'est pas approuvée par la machine cliente.
Correction :
# Réimporter la clé depuis le dépôt
curl -fsSL http://repod.example.com:80/repos/dists/jammy/InRelease \
| gpg --dearmor \
| sudo tee /etc/apt/trusted.gpg.d/repod.gpg > /dev/null
sudo apt update
apt update échoue — 404 Not Found¶
Symptôme :
Cause : la distribution n'a pas été initialisée, ou le nom de
distribution dans sources.list ne correspond à aucun codename pris en
charge.
Correction :
# Réinitialiser les distributions
curl -X POST http://localhost:8000/api/v1/distributions/init \
-H "Authorization: Bearer $TOKEN"
# Vérifier que la distribution existe
ls /repos/dists/
Problèmes clients RPM¶
dnf install échoue — GPG key retrieval failed¶
Symptôme :
warning: /var/cache/dnf/repod/packages/mypackage-1.0.0.rpm: Header V4 RSA/SHA256
Signature, key ID ABCD1234: NOKEY
Cause : la clé GPG n'a pas été importée avant l'activation de
gpgcheck=1.
Correction :
Erreurs createrepo_c dans les logs du backend¶
Symptôme :
Cause : le répertoire de la distribution RPM n'existe pas ou a de mauvaises permissions.
Correction :
# Réinitialiser les distributions RPM
curl -X POST http://localhost:8000/api/v1/distributions/init \
-H "Authorization: Bearer $TOKEN"
# Vérifier les permissions
docker exec backend-api ls -la /repos/almalinux9/
Problèmes de synchronisation / import¶
« Erreur inconnue » pendant la synchronisation (page Import)¶
Symptôme : le flux de synchronisation affiche « Erreur inconnue » immédiatement au démarrage.
Cause (fréquente) : le frontend a été construit avec un ancien bundle
utilisant des URLs d'API incorrectes (préfixe /api/v1 manquant). Le
navigateur utilise l'ancien build mis en cache.
Correction : rafraîchir énergiquement le navigateur (Ctrl+Shift+R /
Cmd+Shift+R). Si le problème persiste, videz le cache du navigateur ou
reconstruisez le frontend :
La synchronisation de l'index renvoie 0 paquet¶
Symptôme : la synchronisation se termine sans erreur mais aucun paquet n'apparaît dans le catalogue.
Cause (APT) : le fichier Release de la source externe ne peut pas être
récupéré (restriction réseau, mauvaise URL, ou clé GPG manquante pour la
source).
Cause (RPM) : le repodata/repomd.xml de la source est inaccessible, ou
la table d'index des paquets PostgreSQL (package_index) est vide/désynchro-
nisée pour cette source.
Diagnostic :
Correction (relancer la synchronisation) :
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"YourPassword"}' | jq -r .access_token)
curl -X POST http://localhost:8000/api/v1/import/sync/start \
-H "Authorization: Bearer $TOKEN"
Problèmes d'authentification¶
La connexion échoue avec des identifiants valides¶
Symptôme : la page de connexion renvoie « Identifiants incorrects » malgré l'utilisation du bon nom d'utilisateur et du bon mot de passe.
Causes possibles :
1. ADMIN_PASSWORD_HASH dans backend.env contient des signes $ non
échappés (ne s'applique que si vous pré-provisionnez un admin — la
plupart des déploiements créent plutôt le premier admin via l'assistant
de configuration, POST /api/v1/setup)
2. La table users est vide (PostgreSQL pas encore initialisé, ou
DATABASE_URL pointe vers la mauvaise base de données)
3. Le compte est désactivé (is_active: false)
4. Aucun compte admin n'existe encore — vérifiez GET /api/v1/setup/status ;
si admin_exists: false, créez-en un via POST /api/v1/setup
Diagnostic :
# Vérifier la table users directement dans PostgreSQL
docker exec repod-db psql -U repod -d repod -c \
"SELECT username, role, is_active FROM users;"
Correction pour l'échappement du hash :
# Dans backend.env : remplacer chaque $ par $$
# Incorrect : ADMIN_PASSWORD_HASH=$2b$12$...
# Correct : ADMIN_PASSWORD_HASH=$$2b$$12$$...
Code MFA rejeté¶
Symptôme : le code TOTP saisi pendant l'authentification MFA est rejeté alors qu'il a bien été généré par l'application d'authentification correcte.
Cause : l'horloge système du serveur diffère de celle du client de plus de 30 secondes. Les codes TOTP sont basés sur le temps et échouent si les horloges ne sont pas synchronisées.
Correction :
# Vérifier l'heure du serveur
docker exec backend-api date
# Synchroniser l'horloge de l'hôte (si NTP est utilisé)
sudo timedatectl set-ntp true
sudo systemctl restart systemd-timesyncd
Problèmes de performance¶
Le backend est lent ou ne répond pas¶
Symptôme : les requêtes API prennent plus de 10 secondes, ou l'endpoint de santé expire.
Cause (la plus fréquente) : ClamAV ou Grype effectue une mise à jour de base de données. C'est intensif en CPU et peut saturer l'allocation CPU du conteneur.
Diagnostic :
Correction : les limites de ressources par défaut dans
docker-compose.yaml sont de 1,5 CPU et 2,5 Go de RAM. Augmentez-les si
votre matériel le permet :
Consultation des logs¶
# Tous les conteneurs
docker compose logs -f
# Backend uniquement, 200 dernières lignes
docker compose logs backend-api --tail=200
# Filtrer les erreurs
docker compose logs backend-api 2>&1 | grep -i "error\|exception\|traceback"
# Journal d'audit (50 dernières entrées)
docker exec backend-api tail -n 50 /repos/audit/$(date +%Y-%m-%d).jsonl | python3 -m json.tool