FWS-ISO/environnement.md

# Environnement de référence — machine hôte qui build FWS

Ce document décrit **l'environnement exact** sur lequel le build FWS fonctionne de bout en bout. Si le build échoue chez toi, **compare ligne par ligne** avec cette config et aligne ce qui diffère.

> ⚠️ Ce n'est pas une simple recommandation : chaque ligne ci-dessous a été vérifiée comme nécessaire (ou suffisante) à un build réussi. Une seule différence peut tout casser (keyring, kernel WSL, sandbox pacman, ligne d'encodage…).

---

## 1. Matériel (host Windows)

| Composant | Valeur de référence | Minimum acceptable | Pourquoi |
|---|---|---|---|
| CPU | AMD Ryzen 9 9950X3D (16 cores / 32 threads) | x86_64 avec **VT-x ou AMD-V activé dans le BIOS** | WSL 2 = Hyper-V → la virtualisation **doit** être activée dans le firmware |
| RAM | 64 GB (61.67 GB utilisable) | 8 GB | `mkarchiso` charge l'image squashfs en RAM ; `makepkg` des paquets AUR compile en parallèle |
| Disque libre sur `C:` | ≥ 130 GB libres | 25 GB libres | WSL grossit dynamiquement ; squashfs intermédiaire peut atteindre 10 GB |
| Architecture | x86_64 | x86_64 | ArchWSL n'existe pas en ARM |

---

## 2. OS hôte

| Composant | Valeur exacte référence | Notes |
|---|---|---|
| OS | **Microsoft Windows 11 Professionnel** | Édition Pro/Entreprise/Éducation recommandée (Hyper-V natif) |
| Version | **10.0.26200** (build 26200) | Windows 11 24H2 ou plus récent |
| Architecture | 64 bits | — |

Vérifier :

```bash
powershell.exe -Command "(Get-CimInstance Win32_OperatingSystem).Caption + ' build ' + (Get-CimInstance Win32_OperatingSystem).BuildNumber"
```

Doit retourner : `Microsoft Windows 11 ... build 26200` (ou supérieur).

---

## 3. Git for Windows + Git Bash

| Composant | Valeur de référence |
|---|---|
| Git | **2.53.0.windows.2** |
| Bash (Git Bash) | **GNU bash 5.2.37(1)-release (x86_64-pc-msys)** |

Vérifier :

```bash
git --version
bash --version | head -1
```

> Git Bash < 2.40 a un quoting cassé sur `wsl.exe` — les scripts plantent silencieusement. Mets à jour si tu es en dessous.

---

## 4. WSL (Windows Subsystem for Linux)

| Composant | Valeur de référence |
|---|---|
| Version WSL | **WSL 2** (WSL 1 = pas supporté) |
| Distribution par défaut | **Arch** |
| Version de la distro | **2** |
| `.wslconfig` (côté Windows, `C:\Users\<toi>\.wslconfig`) | **Absent** (réglages par défaut suffisent) |

Vérifier :

```bash
wsl.exe --status
wsl.exe -l -v
```

Doit afficher exactement :

```
NAME    STATE     VERSION
* Arch    Stopped   2
```

⚠️ **Le nom doit être exactement `Arch`** (sinon exporter `ARCH_WSL_DISTRO=NomChezToi` avant de lancer les scripts).

---

## 5. WSL Arch — kernel et système

| Composant | Valeur de référence | Vérif |
|---|---|---|
| Kernel WSL | **6.6.114.1-microsoft-standard-WSL2** | `wsl.exe -d Arch -- uname -r` |
| Hostname (par défaut) | murasaki (peu importe le tien) | — |
| Distribution | **Arch Linux rolling** | `cat /etc/os-release` |
| Build ID | `20250302.0.316047` (ou plus récent) | — |

Mettre à jour le kernel WSL si nécessaire (PowerShell admin) :

```bash
powershell.exe -Command "Start-Process powershell -Verb RunAs -ArgumentList 'wsl --update'"
```

---

## 6. WSL Arch — `/etc/wsl.conf`

Fichier **obligatoire** : `/etc/wsl.conf` dans la distro Arch.

```ini
[boot]
systemd=true
```

Vérifier :

```bash
wsl.exe -d Arch -u root -- cat //etc/wsl.conf
```

> Sans `systemd=true`, l'activation de `NetworkManager.service` dans le live ne sera pas testable, et `pacman-key --populate` peut bloquer.

Après modification :

```bash
wsl.exe --shutdown
```

(redémarrage complet de la WSL pour appliquer `wsl.conf`).

---

## 7. WSL Arch — pacman

| Composant | Valeur de référence |
|---|---|
| pacman | **v7.1.0** |
| libalpm | **v16.0.1** |
| `/etc/pacman.conf` → `DisableSandbox` | **Présent et décommenté** |

`/etc/pacman.conf` doit contenir, dans la section `[options]` :

```ini
DisableSandbox
```

> pacman ≥ 7 utilise **landlock** pour sandboxer les opérations FS. **Le kernel WSL ne supporte pas landlock** → tout install bloque. `setup-aur.sh` l'ajoute automatiquement la première fois.

Vérifier :

```bash
wsl.exe -d Arch -u root -- grep -E "^DisableSandbox" //etc/pacman.conf
```

Doit retourner : `DisableSandbox` (sans `#`).

---

## 8. WSL Arch — paquets requis

Versions de référence (peuvent évoluer, l'important est que ces paquets soient installés et à jour) :

| Paquet | Version réf | Rôle |
|---|---|---|
| `archiso` | **88-1** | `mkarchiso` (build de l'ISO) |
| `base-devel` | **1-2** | `makepkg`, gcc, make, fakeroot |
| `git` | **2.54.0-1** | clone des paquets AUR |
| `reflector` | **2023-5** | mise à jour des miroirs |
| `dos2unix` | **7.5.5-1** | fix des CRLF Windows |

Vérifier :

```bash
wsl.exe -d Arch -u root -- pacman -Q archiso base-devel git reflector dos2unix
```

Tout doit retourner une version (pas `not found`). Si manquant :

```bash
wsl.exe -d Arch -u root -- pacman -Sy --noconfirm archiso base-devel git reflector dos2unix
```

---

## 9. WSL Arch — keyring pacman

État requis :

- `pacman-key --init` exécuté au moins une fois (crée `/etc/pacman.d/gnupg/`)
- `pacman-key --populate archlinux` exécuté au moins une fois
- `archlinux-keyring` à jour

Vérifier :

```bash
wsl.exe -d Arch -u root -- ls //etc/pacman.d/gnupg/
wsl.exe -d Arch -u root -- pacman -Q archlinux-keyring
```

Le dossier `gnupg/` doit exister et contenir `pubring.gpg`, `trustdb.gpg`, etc.

Si jamais initialisé :

```bash
wsl.exe -d Arch -u root -- bash -c "pacman-key --init && pacman-key --populate archlinux && pacman -Sy --noconfirm archlinux-keyring && pacman -Syu --noconfirm"
```

---

## 10. WSL Arch — espace disque

Mesuré sur la machine de référence :

```
Filesystem      Size  Used Avail Use% Mounted on
tmpfs            16G     0   16G   0% /tmp
/dev/sdd       1007G  4.3G  952G   1% /
```

Vérifier :

```bash
wsl.exe -d Arch -u root -- df -h //tmp /
```

| Point de montage | Minimum |
|---|---|
| `/tmp` (tmpfs) | ≥ 4 GB libres |
| `/` (rootfs WSL) | ≥ 20 GB libres |

> Si `/tmp` n'est pas un `tmpfs`, mkarchiso sera **5-10× plus lent**. Sur WSL avec systemd, c'est tmpfs par défaut.

---

## 11. Variables d'environnement (Git Bash)

Aucune variable n'est requise **pour que ça marche**, mais les scripts en utilisent en interne :

| Variable | Valeur | Quand |
|---|---|---|
| `MSYS_NO_PATHCONV=1` | forcée par `build.sh` et `setup-aur.sh` | empêche Git Bash de convertir `/tmp/...` en chemins Windows |
| `MSYS2_ARG_CONV_EXCL=*` | forcée par `setup-aur.sh` | empêche la conversion d'arguments passés à `wsl.exe` |
| `ARCH_WSL_DISTRO` | optionnel, défaut = `Arch` | nom de la distro WSL si tu as renommé |

---

## 12. Permissions & emplacement du repo

| Critère | Référence |
|---|---|
| Chemin du repo (host) | `C:\Users\<user>\Documents\1. FWS\FWS\` |
| Chemin équivalent WSL | `/mnt/c/Users/<user>/Documents/1. FWS/FWS/` |
| Espaces dans le chemin | **OK** (les scripts gèrent `"1. FWS"`) |
| Caractères accentués dans le chemin | **À éviter** (mkarchiso plante) |
| Antivirus / Defender exclusion sur le dossier | **Recommandé** (gros gain de perf sur `cp -ar`) |

Ajouter une exclusion Defender (PowerShell admin) :

```bash
powershell.exe -Command "Start-Process powershell -Verb RunAs -ArgumentList 'Add-MpPreference -ExclusionPath \"C:\Users\$env:USERNAME\Documents\1. FWS\"'"
```

---

## 13. Réseau

| Critère | État requis |
|---|---|
| Accès internet depuis WSL | obligatoire (pacman, AUR, reflector) |
| Proxy d'entreprise | configurer dans `/etc/wgetrc` + `/etc/pacman.d/mirrorlist` |
| `mirrorlist` à jour | `reflector --latest 10 --sort rate` (fait par `setup-aur.sh`) |

Tester depuis WSL :

```bash
wsl.exe -d Arch -u root -- bash -c "curl -sI https://archlinux.org/ | head -1"
```

Doit retourner : `HTTP/2 200`.

---

## 14. Procédure de remise à zéro complète

Si rien ne fonctionne, **réinitialise la WSL Arch** depuis Git Bash :

```bash
# Sauvegarde le repo FWS d'abord (il est sur C:, donc safe)
wsl.exe --shutdown
wsl.exe --unregister Arch

# Réinstalle ArchWSL
curl.exe -L -o "$TEMP/Arch.zip" "https://github.com/yuk7/ArchWSL/releases/latest/download/Arch.zip"
powershell.exe -Command "Expand-Archive -Force '$env:TEMP\Arch.zip' '$env:LOCALAPPDATA\ArchWSL'"
"$LOCALAPPDATA/ArchWSL/Arch.exe"  # ferme la fenêtre dès qu'elle s'ouvre

# Configure wsl.conf
wsl.exe -d Arch -u root -- bash -c 'printf "[boot]\nsystemd=true\n" > /etc/wsl.conf'
wsl.exe --shutdown

# Init complète
wsl.exe -d Arch -u root -- bash -c "pacman-key --init && pacman-key --populate archlinux && pacman -Sy --noconfirm archlinux-keyring && pacman -Syu --noconfirm && pacman -S --noconfirm --needed archiso base-devel git reflector dos2unix"

# Relance le build
cd "/c/Users/$USER/Documents/1. FWS/FWS"
./setup-aur.sh
./build.sh
```

---

## 15. Checklist rapide de diagnostic

À copier-coller dans Git Bash pour comparer ta machine avec la référence :

```bash
echo "=== Host ===" && powershell.exe -Command "(Get-CimInstance Win32_OperatingSystem).Caption + ' build ' + (Get-CimInstance Win32_OperatingSystem).BuildNumber"
echo "=== Git ===" && git --version
echo "=== Bash ===" && bash --version | head -1
echo "=== WSL ===" && wsl.exe -l -v
echo "=== Kernel ===" && wsl.exe -d Arch -u root -- uname -r 2>&1 | tr -d '\0'
echo "=== pacman ===" && wsl.exe -d Arch -u root -- bash -c "pacman --version | head -2" 2>&1 | tr -d '\0'
echo "=== Sandbox ===" && wsl.exe -d Arch -u root -- grep "^DisableSandbox" //etc/pacman.conf 2>&1 | tr -d '\0'
echo "=== Paquets ===" && wsl.exe -d Arch -u root -- pacman -Q archiso base-devel git reflector dos2unix 2>&1 | tr -d '\0'
echo "=== wsl.conf ===" && wsl.exe -d Arch -u root -- cat //etc/wsl.conf 2>&1 | tr -d '\0'
echo "=== Disque WSL ===" && wsl.exe -d Arch -u root -- df -h / //tmp 2>&1 | tr -d '\0'
```

Compare la sortie avec les valeurs de référence des sections 2 à 10 ci-dessus.

---

## 16. Configuration de référence en une page (résumé)

```
Host        : Windows 11 Pro build 26200, x86_64, VT/AMD-V activé
CPU         : x86_64 (Ryzen 9 9950X3D testé)
RAM         : 64 GB (8 GB min)
Disque libre: ≥ 130 GB sur C:
Git         : 2.53.0.windows.2
Bash        : 5.2.37(1)-release msys
WSL         : version 2, distro "Arch", version 2
Kernel WSL  : 6.6.114.1-microsoft-standard-WSL2
.wslconfig  : absent
wsl.conf    : [boot]\nsystemd=true
pacman      : v7.1.0 / libalpm v16.0.1
pacman.conf : DisableSandbox actif
Keyring     : initialisé + populé + archlinux-keyring à jour
Paquets     : archiso 88-1, base-devel 1-2, git 2.54.0-1,
              reflector 2023-5, dos2unix 7.5.5-1
Repo path   : C:\Users\<user>\Documents\1. FWS\FWS\
              (pas d'accents, espaces OK)
Defender    : exclusion sur le dossier du repo
Réseau      : accès archlinux.org (HTTP/2 200), pas de proxy bloquant
```

Si **tout** ce qui précède est aligné, `./setup-aur.sh && ./build.sh` doit produire `out/FWS-*.iso` en 25-55 min au total.

---

## 17. Build depuis Fedora / Linux non-Arch (bascule conteneur podman)

Les trois scripts (`setup-aur.sh`, `build.sh`, `build-offi.sh`) détectent un hôte
**non-Arch** et se relancent automatiquement à l'identique dans un conteneur Arch
podman. Aucune Arch native ni WSL n'est nécessaire — il suffit d'installer podman.

```bash
sudo dnf install -y podman      # Fedora
sudo apt install -y podman      # Debian / Ubuntu
./setup-aur.sh && ./build.sh    # exactement comme sur Arch
```

### Design (points à NE PAS « simplifier »)

| Choix | Pourquoi |
|---|---|
| **Détection hôte Arch** = `command -v pacman` **ET** `grep -qiE '^ID(_LIKE)?=.*arch' /etc/os-release` | Fedora empaquette aussi `pacman` → sa seule présence ne suffit pas à conclure « hôte Arch ». |
| **podman rootful** (`sudo podman`) | mkarchiso exige des mounts/chroot/loop privilégiés ; podman rootless ne les gère pas. |
| **`--privileged`** | Donne les capabilities mkarchiso **et** relâche SELinux (enforcing sur Fedora) sur le bind-mount, sans avoir besoin de `:Z` (qui relabellerait le dépôt). |
| **`pull` explicite** avant `run` | `run` ne re-résout jamais le tag `latest` une fois l'image en cache → sinon on build sur une image qui vieillit. |
| **`pacman -Syu archiso`** (pas `-Sy`) quand `FWS_IN_CONTAINER=1` | Évite le partial upgrade : sur une image de base vieillissante, `-Sy archiso` tire des deps plus récentes que la base installée. |
| **`FWS_IN_CONTAINER=1`** | Garde anti-récursion **et** active `DisableSandbox` (landlock) comme le chemin WSL. |
| **Dépôt monté au MÊME chemin absolu** + volume `fws-pacman-cache` | `WORK_DIR`, `out/` et `local-repo/` restent identiques côté hôte ; le cache pacman persiste entre les runs. Les artefacts (root, podman rootful) sont re-`chown` vers le propriétaire du dépôt en fin de run. |

> Validé par revue adversariale sur Fedora 43 (podman 5.8.2, SELinux enforcing).
> Image : `docker.io/library/archlinux:latest`.