Gestion des conteneurs

Ce chapitre rassemble les gestes du quotidien pour exploiter les conteneurs de Chatbotaurus. Deux contextes cohabitent :

le développement et les essais, avec podman-compose (podman-compose.yml et podman-compose.vps2.yml) ;
la production, avec des unités Quadlet pilotées par systemd sous le compte non privilégié dédié, <compte-deploiement> (mode rootless : aucune commande sudo podman n'est nécessaire).

Le choix de déploiement est décrit dans Déploiement avec Podman.

Réseaux

Réseau	Plan	Contenu
`chatbotaurus-vps1`	Backend	Services `forge-*`
`mgaas-vps2`	Client	Passerelle MCP et services `mcp-*`

Les adresses de ces réseaux ne sont pas fixées par la documentation : les conteneurs se joignent par leur nom (DNS interne Podman), et PostgreSQL et Valkey portent les alias postgres et valkey sur les deux réseaux.

podman network ls
podman network inspect chatbotaurus-vps1 --format '{{.Name}}'

Commandes courantes

Les commandes ci-dessous valent pour le développement comme pour la production, sauf mention contraire.

Lister les conteneurs

podman ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Journaux d'un conteneur

podman logs -f forge-api
podman logs --tail 100 forge-postgres

Pour une unité Quadlet, le journal systemd donne aussi l'historique des démarrages :

journalctl --user -u forge-api.service -n 100

Redémarrer un service

# Développement
podman-compose -p chatbotaurus-vps1 restart postgres

# Production (unité Quadlet)
systemctl --user restart forge-api.service
systemctl --user status forge-api.service

Résultat attendu : systemctl --user status affiche active (running). Sinon, lisez journalctl --user -u forge-api.service -n 100 et suivez Problèmes connus.

Inspecter un conteneur

podman inspect forge-valkey --format '{{.State.Status}}'

Statistiques de ressources

podman stats --no-stream

Services principaux

Noms de conteneurs du plan backend, avec leur port d'écoute interne :

Conteneur	Port	Rôle
`forge-postgres`	5432	Base de données principale
`forge-valkey`	6379	Cache et sessions
`forge-qdrant`	6333 (REST), 6334 (gRPC)	Base vectorielle
`forge-ollama`	11434	Inférence IA locale (limite mémoire fixée dans le plan compose)
`forge-authentik`	9000	SSO / IAM (en production : `forge-authentik-server` et `forge-authentik-worker`)
`forge-openbao`	8200	Gestion des secrets
`forge-api`	3000	Backend Rust
`forge-victoriametrics`	8428	Métriques
`forge-victorialogs`	9428	Journaux
`forge-crowdsec`	—	Détection d'intrusion
`forge-seaweedfs`	8333	Stockage objet S3

En production, forge-traefik est l'ingress du plan backend et mcp-caddy celui du plan client.

Les limites mémoire déclarées se lisent dans les fichiers :

grep -n "memory:" podman-compose.yml

Mise à jour d'un service

La marche diffère selon le contexte.

En production

La mise à jour est tirée par l'hôte. Un minuteur, 2 minutes après la fin du passage précédent, reconstruit l'image backend ou le front quand la branche principale avance. Voir la section « Déploiement tiré par l'hôte » du chapitre Déploiement avec Podman. Pour suivre l'état du front (ce script ne lit pas celui du backend : comparez le champ sha de /api/v1/healthz au commit attendu) :

bash scripts/deploy/suivre-autodeploy.sh

Si une image doit être rétablie à la main : l'étiquette précédente reste sur l'hôte (podman images | grep forge-stack). Remettez-la dans l'unité forge-api.container, puis :

systemctl --user daemon-reload
systemctl --user restart forge-api.service

En développement

Si le service porte des données (PostgreSQL, Valkey, Qdrant), sauvegardez-les d'abord : Sauvegarde et restauration.

podman-compose -p chatbotaurus-vps1 pull postgres
podman-compose -p chatbotaurus-vps1 up -d postgres

Sauvegardes

Les sauvegardes sont décrites dans Sauvegarde et restauration. Les commandes manuelles sont les mêmes que celles utilisées par scripts/backup/nightly.sh.

Dépannage

Quelques pannes fréquentes et le premier geste à faire.

Conteneur qui ne démarre pas

# Logs du conteneur
podman logs forge-postgres

# Ports occupés (Linux)
ss -tlnp | grep 5432

# Espace disque
df -h

Vérifiez aussi que les deux réseaux existent : podman network ls. Les fichiers compose les déclarent externes et ne les créent pas. Les volumes de données sont dans le même cas : podman volume ls, et la boucle de création de Déploiement avec Podman.

Conflit de port

# Linux
ss -tlnp | grep <port>

# Windows (développement local)
netstat -ano | Select-String "5432"

Le port de Valkey publié sur l'hôte est 6380 par défaut, pour éviter une collision avec un Redis local sur le port 6379.

Ollama ne charge pas le modèle

# Mémoire disponible
free -h

# Modèles installés
podman exec forge-ollama ollama list

# Télécharger un modèle manquant
podman exec forge-ollama ollama pull <nom-du-modèle>

Un service attend un autre

Les services du compose déclarent des sondes de santé (healthcheck) : PostgreSQL, Valkey et Qdrant doivent être sains avant le démarrage du service forge-api. Vérifiez l'état avec :

podman ps --format "table {{.Names}}\t{{.Status}}"

Voir aussi

Déploiement avec Podman — créer les réseaux et volumes, démarrer les plans, unités Quadlet
Sauvegarde et restauration — sauvegarder PostgreSQL, Valkey, Qdrant et OpenBao avant toute mise à jour
Problèmes connus — solutions détaillées aux pannes de conteneurs, ports, DNS et volumes
Diagnostics et signalement — routes de santé, vérification manuelle des services et ressources
Journaux — format des journaux du backend et filtres de verbosité par module

Raccourcis clavier