Vagga est un moteur de conteneurs fonctionnant entièrement en espace utilisateur, sans recourir à un démon. Bien que conçu pour simplifier la mise en place d'environnements de développement reproductibles, certains obstacles techniques peuvent suvrenir lors de son utilisation. Ce guide passe en revue les principaux dysfonctionnements et leurs remèdes.

1. Problèmes liés aux fichiers /etc/subuid et /etc/subgid

---

L'erreur suivante indique que Vagga ne trouve pas les fichiers de mappage d'identifiants :

ERREUR: vagga::container::uidmap: Impossible de lire uidmap: /etc/subuid introuvable (erreur système 2)
ATTENTION: vagga::container::uidmap: Échec de lecture de /etc/subuid ou /etc/subgid

Procédure de résolution :

• Créer les fichiers s'ils sont absents :

sudo touch /etc/subuid /etc/subgid

• Ajouter la correspondance utilisateur dans /etc/subuid :

votre_utilisateur:100000:65536

• Répéter l'opération dans /etc/subgid avec la même syntaxe.
• Vérifier les permissions :

sudo chmod 644 /etc/subuid /etc/subgid

2. Commandes newuidmap et newgidmap introuvables

---

Le message d'avertissement suivant apparaît quand les binaires de mappage d'UID/GID ne sont pas installés :

ATTENTION: vagga::process_util: `newuidmap` ou `newgidmap` absent

Installation selon la distribution :

# Debian / Ubuntu
sudo apt-get install uidmap

# Fedora / RHEL / CentOS
sudo dnf install shadow-utils

# Arch Linux
sudo pacman -S shadow

3. Exécution en tant que root

---

Vagga doit être lancé par un utilisateur non privilégié. L'avertissement ci-dessous signale une inadéquation entre le propriétaire du projet et l'utilisateur courant :

ATTENTION: vagga::launcher: Vagga est lancé par un utilisateur différent du propriétaire du répertoire projet.

Étapes de vérification :

1. Inspecter le propriétaire du dossier .vagga :

ls -la .vagga/

2. Si une exécution root a déjà eu lieu, supprimer le dossier et le régénérer :

sudo rm -rf .vagga

3. S'assurer que le noyau est en version 3.9 minimum :

uname -r

4. Vérifier l'activation des user namespaces non privilégiés :

sysctl kernel.unprivileged_userns_clone

La valeur attendue est 1 ou l'absence de la clé.

4. Mémoire partagée insuffisante

---

Certains outils comme Flow consomment beaucoup de mémoire partagée POSIX. L'erreur se manifeste ainsi :

Épuisement des systèmes de fichiers disponibles pour la mémoire partagée

Solution : augmenter la taille du tmpfs dans vagga.yaml :

containers:
  mon_conteneur:
    volumes:
      /run: !Tmpfs
        size: 1Gi
        subdirs:
          shm:

5. Incompatibilité avec les dossiers partagés de machines virtuelles

---

L'utilisation de dossiers partagés VirtualBox ou VMware provoque des erreurs de permissions :

ERREUR: Impossible de définir le propriétaire de bin/bbsuid.apk-new: Opération non permise

Recommandations :

• Ne pas utiliser de répertoires réseau ou partagés pour le cache Vagga.
• Préférer un stockage local pour .vagga.
• Consulter la documentation settings.rst pour redéfinir le chemin de stockage.

6. Limite d'inotify atteinte

---

Les outils de surveillance de fichiers peuvent déclencher l'erreur suivante :

inotify watch limit reached
ENOSPC / No space left on device

Correction :

# Ajustement temporaire
sudo sysctl fs.inotify.max_user_watches=524288

# Rendre persistant
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf

Vagga peut également ajuster automatiquement ce paramètre si l'option auto-apply-sysctl est activée.

7. Support d'OverlayFS

---

Vagga exploite OverlayFS pour optimiser les performances. Vérifier la compatibilité :

vagga _check_overlayfs_support

Notes par distribution :

• Ubuntu 14.04+ : support natif.
• Arch Linux : nécessite un noyau patché.
• NixOS : configuration manuelle du noyau requise.

8. Échecs de construction de conteneurs

---

Les erreurs de build sont souvent liées au cache, au réseau ou aux dépendances.

Démarche :

# Purger le cache local
vagga _clean

# Build avec journalisation détaillée
vagga _build --verbose

Vérifier également la connectivité réseau et les éventuels paramètres de proxy.

9. Incompatibilités de version

---

La version 0.2 a introduit des changements dans le format vagga.yaml. Pour migrer :

1. Sauvegarder la configuration existante.

2. Consulter RELEASE_NOTES.rst pour les changements cassants.

3. Adapter progressivement les sections concernées.

4. Tester chaque commande après modification.

5. Erreurs de syntaxe dans vagga.yaml

---

Les erreurs de syntaxe YAML sont fréquentes. Pour les détecter :

python3 -c "import yaml; yaml.safe_load(open('vagga.yaml'))"

Points d'attention :

• Respecter strictement l'indentation (espaces, pas de tabulations).
• Se référer à config.rst pour la structure des commandes.

Procédure de diagnostic rapide

1. Vérifier les mappages d'UID/GID et les propriétaires de fichiers.
2. Confirmer la version du noyau et le support des user namespaces.
3. Lancer Vagga avec le flag --verbose.
4. Tester avec un fichier vagga.yaml minimal.
5. Consulter la documentation errors.rst.

Bonnes pratiques préventives

• Maintenir Vagga à jour.
• Suivre les configurations avec Git.
• Surveiller l'espace disque occupé par les images.
• Consulter régulièrement config.rst, commands.rst, build_steps.rst et container_params.rst.