+ 
-
+
- Configuration utilisateur reproductible pour une station Arch Linux sous - Wayland, déployée package par package avec GNU Stow. + Environnement utilisateur Arch Linux reproductible, composé avec GNU Stow.
- Arch Linux · Sway · GNU Stow ·
- systemd --user · Zsh
+ 
- Overview · - Desktop · - Shell · - Layout · - Deployment · - Rebuild + Overview · + Stack · + Preview · + Quick Start · + Documentation · + Version
- - ## ✦ Overview -Ce dépôt contient la couche **utilisateur** d'ArchASP : session graphique, -applications terminal, shell, scripts personnels et unités systemd user. La -couche **système/root** est volontairement séparée. +`Dotfiles_ArchAP` décrit la couche **utilisateur** d'ArchASP : session Wayland, +shell, applications terminal, scripts personnels et unités systemd user. Chaque +package reproduit son chemin sous `$HOME` et GNU Stow déploie les liens +symboliques correspondants. -| Dépôt | Responsabilité | +L'administration système reste séparée dans +[`arch-system`](https://git.labfytools.com/fy59/arch-system) : installation +Arch, boot, stockage, réseau, paquets, `/etc` et helpers root. Les inventaires +de ce dépôt documentent la machine réelle, mais ne constituent pas un +installateur automatique. + +## ✦ Stack + +| Desktop | Shell | | --- | --- | -| **`.dotfiles`** | Sway, Kitty, Neovim, Zsh, scripts, thèmes et services utilisateur | -| **[`arch-system`](https://git.labfytools.com/fy59/arch-system)** | Installation Arch, boot, stockage, réseau, paquets, `/etc` et helpers root | +| `greetd → tuigreet → UWSM → Sway` | `Zsh → Starship → Atuin` | +| `Swaybar → i3status-rs` | `FZF → Zoxide → Eza → Bat → Yazi` | +| Mako · Wofi · Swaylock · Cliphist · Kitty | plugins Zsh et Tmux épinglés par sous-modules | -Cette séparation évite de mêler état personnel et administration système. Le -dépôt reste néanmoins spécifique à la machine : sorties Sway, périphériques, -chemins sous `/home/fy59` et projets externes doivent être relus avant un -déploiement ailleurs. - - - -## ✦ Desktop Stack - -```text -greetd - └─ tuigreet - └─ UWSM - └─ Sway - ├─ Swaybar ── i3status-rs - ├─ Mako notifications - ├─ Wofi launcher - ├─ Swaylock verrouillage - ├─ Cliphist historique du presse-papiers - └─ Kitty terminal +```mermaid +flowchart LR + G[greetd] --> T[tuigreet] --> U[UWSM] --> S[Sway] + S --> B[Swaybar] --> I[i3status-rs] + S --> M[Mako] + S --> W[Wofi] + S --> L[Swaylock] + S --> C[Cliphist] + S --> K[Kitty] ``` -| Fonction | Composant canonique | -| --- | --- | -| Session | `greetd → tuigreet → uwsm start default → sway.desktop` | -| Compositor | Sway / SwayFX | -| Barre | Swaybar avec i3status-rs | -| Notifications | Mako | -| Launcher | Wofi | -| Verrouillage et idle | Swaylock + swayidle | -| Presse-papiers | wl-clipboard + Cliphist | -| Terminal | Kitty | -| Profils d'énergie | TLP via l'interface utilisateur `tlpctl` | +Les responsabilités et dépendances sont détaillées dans +[`docs/desktop.md`](docs/desktop.md) et [`docs/shell.md`](docs/shell.md). -`uwsm/.config/uwsm/default-id` sélectionne `sway.desktop`. La copie de -référence de greetd se trouve dans `.assets/greetd/config.toml`; son -installation sous `/etc/greetd` appartient à `arch-system`. +## ✦ Preview - +
+ 
+
Environnement ArchASP réel — Sway, applications terminal et palette Catppuccin.
+ +## ✦ Repository ```text -Zsh - ├─ Starship - ├─ Atuin - ├─ FZF - ├─ Zoxide - ├─ Eza - ├─ Bat - └─ Yazi +ArchASP +├── arch-system système/root · /etc · services système · installation +└── Dotfiles_ArchAP utilisateur · $HOME · Stow · systemd --user ``` -`.zprofile` démarre la session graphique via UWSM lorsque celui-ci autorise un -démarrage. `.zshenv` publie le socket de l'agent SSH utilisateur. L'historique, -les bases et la clé Atuin restent strictement locaux et hors Git. +Les 31 packages Stow couvrent le desktop, le shell, le développement, les +services utilisateur et l'apparence. `.assets/` contient les inventaires de +reconstruction ; `docs/` contient la documentation et n'est jamais un package +Stow. Voir le [contrat d'architecture](docs/architecture.md). - +## ✦ Quick Start -## ✦ Repository Layout - -Chaque répertoire de premier niveau, hors `.assets` et `.git`, est un package -GNU Stow indépendant. Son arborescence reproduit le chemin attendu depuis -`$HOME`. - -```text -.dotfiles/ -├── sway/.config/sway/ → ~/.config/sway/ -├── i3status-rust/.config/ → ~/.config/i3status-rust/ -├── kitty/.config/kitty/ → ~/.config/kitty/ -├── nvim/.config/nvim/ → ~/.config/nvim/ -├── systemd/.config/systemd/user/ → ~/.config/systemd/user/ -├── bin/.local/bin/ → ~/.local/bin/ -├── zsh/.zshrc → ~/.zshrc -├── zsh/.zprofile → ~/.zprofile -└── .assets/ inventaires et références, non déployés -``` - -### Packages principaux - -| Groupe | Packages Stow | -| --- | --- | -| Desktop | `sway`, `swaylock`, `mako`, `wofi`, `cliphist`, `i3status-rust` | -| Terminal et shell | `kitty`, `zsh`, `starship`, `atuin`, `fzf`, `eza`, `bat`, `yazi` | -| Développement | `nvim`, `tmux`, `opencode`, `bin` | -| Services | `systemd`, `uwsm` | -| Apparence | `gtk-3.0`, `gtklock`, `qt5ct`, `qt6ct`, `themes`, `icons`, `wallpapers` | -| Outils | `btop`, `fastfetch`, `hyprwhspr`, `ytmusic-tui` | - -Les thèmes, icônes et wallpapers sont volontairement versionnés. Les -exécutables issus de projets externes restent hors Git même lorsqu'un script -ou une unité user les utilise. - -### Sous-modules - -Les plugins Zsh et Tmux sont épinglés par Git : - -| Intégration | Chemin | -| --- | --- | -| Fast Syntax Highlighting | `zsh/.zsh/plugins/fast-syntax-highlighting` | -| FZF Tab | `zsh/.zsh/plugins/fzf-tab` | -| Zsh Autosuggestions | `zsh/.zsh/plugins/zsh-autosuggestions` | -| Catppuccin Tmux | `tmux/.config/tmux/plugins/catppuccin/tmux` | - - - -## ✦ Deployment - -### Prérequis - -- Git ; -- GNU Stow ; -- les paquets décrits dans `.assets` ; -- une sauvegarde des fichiers existants qui pourraient entrer en conflit. - -### Clone +Le chemin heureux utilise Bash pour le tableau des packages : ```bash git clone --recurse-submodules \ ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git \ "$HOME/.dotfiles" - cd "$HOME/.dotfiles" -git submodule update --init --recursive -``` -### Dry-run Stow - -Construire la liste des packages à partir des répertoires de premier niveau : - -```bash -mapfile -t packages < <( - find . -mindepth 1 -maxdepth 1 -type d \ - ! -name .git ! -name .assets -printf '%f\n' | sort -) +packages=(atuin bat bin btop cliphist eza fastfetch fzf gtk-3.0 gtklock \ + hyprwhspr i3status-rust icons kitty mako nvim opencode qt5ct qt6ct \ + starship sway swaylock systemd themes tmux uwsm wallpapers wofi yazi \ + ytmusic-tui zsh) stow --no --verbose=2 --target="$HOME" "${packages[@]}" -``` - -Examiner tout conflit avant le déploiement réel : - -```bash stow --verbose=2 --target="$HOME" "${packages[@]}" ``` -> Stow reçoit les **noms des packages**. La racine du dépôt n'est pas un -> package : ne pas utiliser `stow .`. +Le dry-run doit être examiné avant le déploiement. Les prérequis, conflits, +inventaires et validations sont décrits dans le +[guide d'installation](docs/installation.md). - +## ✦ Documentation -## ✦ Package Inventory +| Guide | Sujet | +| --- | --- | +| [Documentation](docs/README.md) | Index et responsabilités des documents | +| [Architecture](docs/architecture.md) | Frontières ArchASP, Stow et données locales | +| [Installation](docs/installation.md) | Clone neuf, sous-modules, Stow et validations | +| [Desktop](docs/desktop.md) | Chaîne greetd/UWSM/Sway et composants Wayland | +| [Shell](docs/shell.md) | Zsh, outils interactifs, plugins et scripts | +| [systemd](docs/systemd.md) | Services système et unités utilisateur | +| [Packages](docs/packages.md) | Inventaires Pacman, AUR, services et outils externes | +| [Recovery](docs/recovery.md) | Reconstruction complète après perte du disque | +| [Security](docs/security.md) | Secrets exclus et règles de publication | -| Fichier | Source | Contenu | -| --- | --- | --- | -| `.assets/pkglist-pacman.txt` | `pacman -Qqen` | Paquets officiels explicitement installés | -| `.assets/pkglist-aur.txt` | `pacman -Qqem` | Paquets foreign/AUR explicitement installés | -| `.assets/enabled-services.txt` | systemd système | Services système activés | -| `.assets/enabled-system-aux-units.txt` | systemd système | Timers, sockets et paths activés | -| `.assets/enabled-user-aux-units.txt` | systemd user | Timers, sockets et paths utilisateur activés | -| `.assets/external-tools.md` | inventaire manuel | Cargo, npm, builds locaux, projets et helpers `/usr/local` | +## ✦ Mirrors -Ces fichiers sont des instantanés vérifiables, pas un installateur. Les paquets -AUR, outils Cargo/npm et builds locaux doivent être restaurés séparément. +| Rôle | Dépôt | +| --- | --- | +| Upstream principal | [Forgejo](https://git.labfytools.com/fy59/Dotfiles_ArchAP) | +| Miroir public | [GitHub](https://github.com/labfytools/Dotfiles_ArchAP) | - +Le fetch d'`origin` reste attaché à Forgejo. Ses deux URLs de push publient +vers Forgejo et GitHub. -## ✦ Services +## ✦ Version -Le package `systemd` contient les unités utilisateur ainsi que leurs liens -d'activation relatifs. Il couvre notamment Cliphist, swayidle, GNOME Keyring, -l'agent SSH, les notifications de batterie et les intégrations Trainlog, -Lardon et Arch Sentinel. +| Branche | Rôle | +| --- | --- | +| `0.1.0` | Snapshot stable de la première version nettoyée et documentée | +| `main` | Développement courant | -Après une modification : - -```bash -systemctl --user daemon-reload -systemd-analyze --user verify ~/.config/systemd/user/*.service -``` - -Certaines unités lancent du code externe au dépôt. Leurs chemins et -dépendances sont documentés dans `.assets/external-tools.md`. Les services -système et toute modification de `/etc` restent sous la responsabilité -d'`arch-system`. - - - -## ✦ Secrets - -Ce dépôt n'a pas vocation à contenir : - -- clés SSH, GPG, WireGuard ou Atuin ; -- `.netrc`, mots de passe, tokens, cookies ou credentials ; -- configurations privées Rclone, GitHub CLI ou Nextcloud ; -- bases de données, historiques shell ou états applicatifs personnels. - -Les ignorer dans le HEAD ne suffit pas : un secret déjà commité doit être -renouvelé, puis supprimé de tout l'historique avant publication. - - - -## ✦ Rebuilding ArchASP - -```text -┌──────────────────────────────────────────────────────┐ -│ arch-system │ -│ Arch · boot · stockage · réseau · paquets · /etc │ -└──────────────────────────┬───────────────────────────┘ - │ socle système prêt - ▼ -┌──────────────────────────────────────────────────────┐ -│ .dotfiles │ -│ Stow · session · shell · scripts · systemd user │ -└──────────────────────────┬───────────────────────────┘ - │ restaurations externes - ▼ -┌──────────────────────────────────────────────────────┐ -│ AUR · Cargo/npm · projets locaux · secrets · données│ -└──────────────────────────────────────────────────────┘ -``` - -Ordre de reconstruction recommandé : - -1. restaurer la couche système avec `arch-system` ; -2. installer Git et GNU Stow ; -3. cloner ce dépôt avec ses sous-modules ; -4. restaurer les paquets officiels puis examiner les paquets AUR ; -5. effectuer le dry-run et déployer les packages Stow ; -6. restaurer les outils Cargo/npm et les projets locaux nécessaires ; -7. restaurer les secrets et données applicatives depuis une sauvegarde sûre ; -8. valider puis activer les unités systemd voulues. - -Le dépôt ne reconstruit pas seul les projets sous `Documents`, OpenMVS local, -les helpers `/usr/local`, les secrets, les bases applicatives ou les réglages -matériels propres à la machine. - - - -## ✦ Repository Mirrors - -| Rôle | Hébergement | URL | -| --- | --- | --- | -| Upstream principal | Forgejo | `ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git` | -| Miroir public | GitHub | `https://github.com/labfytools/Dotfiles_ArchAP` | - -Le fetch d'`origin` reste attaché à Forgejo. Ses URLs de push publient vers -Forgejo et GitHub afin qu'un `git push origin main` maintienne les deux copies. - - +La branche stable est immobile : les développements suivants avancent sur +`main` sans déplacer automatiquement `0.1.0`. ## ✦ License -Aucune licence n'est actuellement déclarée pour ce dépôt. +Aucune licence n'est actuellement déclarée pour ce dépôt. En l'absence de +licence, aucun droit de réutilisation n'est accordé implicitement. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..2001c2bd3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,42 @@ +# Documentation ArchASP Dotfiles + +Cet index répartit la documentation par responsabilité. Le `README.md` racine +est la page d'accueil ; les pages ci-dessous portent les procédures et les +limites détaillées. + +## Commencer ici + +| Document | Responsabilité | +| --- | --- | +| [Architecture](architecture.md) | Séparation `arch-system` / dotfiles, contrat Stow et frontières de propriété | +| [Installation](installation.md) | Déploiement depuis un clone neuf et contrôles associés | +| [Recovery](recovery.md) | Reconstruction complète après perte de la machine | + +## Environnement utilisateur + +| Document | Responsabilité | +| --- | --- | +| [Desktop](desktop.md) | Session greetd/UWSM/Sway et composants Wayland canoniques | +| [Shell](shell.md) | Zsh, outils interactifs, plugins et scripts utilisateur | +| [systemd](systemd.md) | Limite système/user, unités et activations utilisateur | + +## Inventaires et sécurité + +| Document | Responsabilité | +| --- | --- | +| [Packages](packages.md) | Snapshots Pacman/AUR, services et dépendances externes | +| [Security](security.md) | Données interdites dans Git et règles de contrôle | + +## Règle de propriété + +Une information détaillée possède une page principale. Le README racine la +résume et pointe vers cette page ; il ne doit pas recopier l'intégralité des +procédures. Les fichiers de `.assets/` sont des inventaires factuels, pas une +deuxième documentation normative ni un installateur. + +## Portée de la version 0.1.0 + +`0.1.0` est le snapshot stable de la première version nettoyée, documentée et +publiée. `main` demeure la branche de développement. La documentation décrit +l'état de ce snapshot ; toute évolution ultérieure doit être portée par +`main` avant une éventuelle nouvelle branche stable. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..5eb9d9042 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,86 @@ +# Architecture + +## Contrat global + +ArchASP sépare volontairement la couche système de la couche utilisateur. + +```mermaid +flowchart TB + A[ArchASP] --> S[arch-system] + A --> D[Dotfiles_ArchAP] + S --> SR[Installation Arch · boot · stockage · réseau] + S --> SE[/etc · services système · helpers root] + D --> DH[$HOME · configuration utilisateur] + D --> DU[Stow · systemd --user · scripts] +``` + +| Couche | Possède | Ne possède pas | +| --- | --- | --- | +| `arch-system` | installation, partitions, boot, paquets de base, `/etc`, greetd installé, services système, helpers `/usr/local` | préférences et fichiers sous `$HOME` | +| `Dotfiles_ArchAP` | session utilisateur, shell, applications terminal, scripts, thèmes, unités `systemd --user` | configuration root, secrets, données applicatives | + +La copie de référence de greetd située dans `.assets/greetd/config.toml` +documente l'intégration, mais son installation dans `/etc/greetd` appartient +à `arch-system`. + +## Contrat GNU Stow + +Chaque package de premier niveau reproduit une arborescence relative à +`$HOME`. GNU Stow crée les liens symboliques ; le dépôt reste la source du +fichier versionné. + +```mermaid +flowchart LR + P[kitty/.config/kitty/kitty.conf] -->|stow kitty| H[~/.config/kitty/kitty.conf] + Z[zsh/.zshrc] -->|stow zsh| R[~/.zshrc] + U[systemd/.config/systemd/user/] -->|stow systemd| Y[~/.config/systemd/user/] +``` + +Exemples de correspondance : + +| Source versionnée | Cible utilisateur | +| --- | --- | +| `sway/.config/sway/` | `~/.config/sway/` | +| `i3status-rust/.config/i3status-rust/` | `~/.config/i3status-rust/` | +| `bin/.local/bin/` | `~/.local/bin/` | +| `zsh/.zprofile` | `~/.zprofile` | +| `wallpapers/.wallpapers/` | `~/.wallpapers/` | + +Les packages Stow sont une liste explicite de 31 noms, détaillée dans le +[guide d'installation](installation.md). Il ne faut pas déduire cette liste de +tous les répertoires de premier niveau : `.assets/` et `docs/` ne sont pas des +packages. Il ne faut jamais exécuter `stow .`. + +## Frontières de propriété + +### Dans les dotfiles + +- configuration déclarative sous `$HOME` ; +- scripts personnels déployés dans `~/.local/bin` ; +- unités et liens d'activation `systemd --user` ; +- thèmes, icônes et fonds d'écran nécessaires à l'environnement ; +- inventaires de reconstruction sous `.assets/` ; +- références Git des plugins Zsh et Tmux via sous-modules. + +### Dans `arch-system` + +- opérations privilégiées et fichiers sous `/etc` ; +- activation des services système, dont greetd ; +- configuration du boot, du stockage, du réseau et de la sécurité système ; +- helpers locaux sous `/usr/local` ; +- restauration initiale des paquets sur une installation minimale. + +### Dans les projets externes + +Trainlog, Lardon, Arch Sentinel, OpenMVS et les autres projets locaux gardent +leur code, leurs builds et leurs données dans leurs propres dépôts. Les +dotfiles peuvent référencer leurs commandes ou unités, sans en devenir la +source. Les chemins attendus sont inventoriés dans +[`external-tools.md`](../.assets/external-tools.md). + +### Machine-local ou secret + +Les bases applicatives, caches, historiques, identités SSH/GPG, clés Atuin, +tokens, cookies et credentials ne sont ni des dotfiles ni des dépendances à +publier. Ils doivent être restaurés séparément depuis une sauvegarde sûre. La +[politique de sécurité](security.md) détaille cette frontière. diff --git a/docs/assets/banner.png b/docs/assets/banner.png new file mode 100644 index 000000000..8766112d4 Binary files /dev/null and b/docs/assets/banner.png differ diff --git a/.assets/screen.jpg b/docs/assets/screenshots/archasp.png similarity index 100% rename from .assets/screen.jpg rename to docs/assets/screenshots/archasp.png diff --git a/docs/desktop.md b/docs/desktop.md new file mode 100644 index 000000000..4b226cb05 --- /dev/null +++ b/docs/desktop.md @@ -0,0 +1,72 @@ +# Desktop + +## Stack canonique + +```mermaid +flowchart LR + G[greetd] --> T[tuigreet] + T --> U[UWSM] + U --> S[Sway] + S --> B[Swaybar] + B --> I[i3status-rs] + S --> M[Mako] + S --> W[Wofi] + S --> L[Swaylock] + S --> C[Cliphist] + S --> K[Kitty] +``` + +| Composant | Responsabilité | Propriété | +| --- | --- | --- | +| greetd | gestionnaire de connexion système | installé/configuré par `arch-system` | +| tuigreet | interface terminal de greetd | paquet système ; commande référencée par greetd | +| UWSM | cycle de vie de la session Wayland | package Stow `uwsm` et paquet système | +| Sway | compositeur et configuration de session | package `sway` | +| Swaybar | barre native de Sway | bloc `bar` de la configuration Sway | +| i3status-rs | contenu et modules de la barre | package `i3status-rust` | +| Mako | notifications Wayland | package `mako` | +| Wofi | lanceur d'applications | package `wofi` | +| Swaylock | verrouillage | package `swaylock`, appelé par les bindings et swayidle | +| Cliphist | historique texte/image du presse-papiers | package `cliphist` et unités user | +| Kitty | terminal principal | package `kitty` | + +La configuration `uwsm/.config/uwsm/default-id` sélectionne `sway.desktop`. +La référence greetd de `.assets/greetd/config.toml` démarre la chaîne système, +mais sa copie dans `/etc` ne relève pas des dotfiles. + +## Session Sway + +Le package `sway` sépare la configuration principale, les bindings, les règles, +le style, la barre, l'autostart et les scripts. Swaybar exécute : + +```text +i3status-rs ~/.config/i3status-rust/config.toml +``` + +Les scripts locaux sous `~/.config/sway/scripts` restent propres à la session. +Les commandes sous `~/.local/bin` sont fournies par le package `bin` ou, quand +cela est documenté, par un projet externe. + +## Services de session + +- `cliphist-text.service` et `cliphist-image.service` observent `wl-paste` ; +- `swayidle.service` verrouille, éteint/rallume les sorties et suspend les + lecteurs selon les délais configurés ; +- `wlsunset.service` gère la température de couleur ; +- `gnome-keyring-daemon.service` et `ssh-agent.service` fournissent les agents + de session ; +- Mako est le fournisseur de notifications retenu. + +Les unités attachées à `graphical-session.target` ne remplacent pas UWSM : +elles consomment le cycle de vie de la session qu'UWSM expose à systemd user. + +## Dépendances visibles + +Les bindings Sway appellent notamment `pactl`, `brightnessctl`, `grim`, +`slurp`, `wl-copy`, `wofi`, `swaylock`, `yazi` et des scripts de +`~/.local/bin`. Les programmes spécifiques à des projets ou à la machine sont +inventoriés dans [`external-tools.md`](../.assets/external-tools.md). + +Les anciens choix Mango, Waybar, SwayNC et Wlogout ne font pas partie de la +stack supportée. Leur éventuelle présence comme paquet installé ne leur donne +aucun rôle dans l'architecture actuelle. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..97c450ff5 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,133 @@ +# Installation + +Ce guide déploie la couche utilisateur depuis un clone neuf. Il n'installe pas +Arch Linux, ne modifie pas `/etc` et n'automatise pas les dépendances externes. +Pour une reconstruction complète, commencer par [Recovery](recovery.md). + +## 1. Prérequis + +- une installation ArchASP dont la couche système est prête ; +- un compte utilisateur et un `$HOME` sauvegardé avant tout remplacement ; +- Git, GNU Stow et Bash ; +- un accès au dépôt Forgejo ou au miroir GitHub ; +- les paquets examinés dans les inventaires de `.assets/`. + +Vérifier les outils avant de continuer : + +```bash +git --version +stow --version +bash --version +``` + +## 2. Cloner + +Forgejo est l'upstream principal : + +```bash +git clone --recurse-submodules \ + ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git \ + "$HOME/.dotfiles" +cd "$HOME/.dotfiles" +``` + +Le miroir public peut servir de source de récupération : + +```bash +git clone --recurse-submodules \ + https://github.com/labfytools/Dotfiles_ArchAP.git \ + "$HOME/.dotfiles" +cd "$HOME/.dotfiles" +``` + +Pour restaurer le snapshot stable plutôt que `main` : + +```bash +git switch 0.1.0 +``` + +## 3. Vérifier les sous-modules + +```bash +git submodule update --init --recursive +git submodule status --recursive +``` + +Une ligne commençant par `-` indique un sous-module non initialisé ; une ligne +commençant par `+` indique un commit différent de celui épinglé. + +## 4. Examiner les inventaires + +Les listes Pacman et AUR sont des snapshots, pas des commandes aveugles à +installer. Comparer leur contenu à la machine cible et lire +[`packages.md`](packages.md) ainsi que +[`external-tools.md`](../.assets/external-tools.md) avant toute installation. + +## 5. Définir les 31 packages Stow + +Les commandes suivantes sont destinées à Bash : + +```bash +packages=( + atuin bat bin btop cliphist eza fastfetch fzf gtk-3.0 gtklock + hyprwhspr i3status-rust icons kitty mako nvim opencode qt5ct qt6ct + starship sway swaylock systemd themes tmux uwsm wallpapers wofi yazi + ytmusic-tui zsh +) + +printf '%s\n' "${packages[@]}" +``` + +`docs/` et `.assets/` ne doivent pas être ajoutés à ce tableau. + +## 6. Effectuer le dry-run + +Depuis la racine du dépôt : + +```bash +stow --no --verbose=2 --target="$HOME" "${packages[@]}" +``` + +Lire chaque conflit. Un fichier réel déjà présent à la cible peut masquer ou +bloquer un lien Stow ; le sauvegarder et décider explicitement de sa source +avant le déploiement. Ne pas utiliser d'option d'adoption sans audit préalable. + +## 7. Déployer + +Une fois le dry-run accepté : + +```bash +stow --verbose=2 --target="$HOME" "${packages[@]}" +``` + +Cette commande crée ou met à jour des liens sous `$HOME`. Elle ne doit pas être +exécutée depuis une autre racine ni avec `.` comme nom de package. + +## 8. Recharger systemd user + +Les liens d'activation versionnés dans le package `systemd` expriment les +unités utilisateur attendues. Recharger et vérifier avant tout démarrage : + +```bash +systemctl --user daemon-reload +systemd-analyze --user verify \ + "$HOME"/.config/systemd/user/*.service \ + "$HOME"/.config/systemd/user/*.timer +systemctl --user --failed +``` + +Certaines unités dépendent de projets externes. Ne les démarrer que lorsque +leurs chemins et configurations locales existent ; voir [`systemd.md`](systemd.md). + +## 9. Valider + +```bash +git status --short +git submodule status --recursive +find "$HOME/.config" -xtype l -print +systemctl --user --failed +sway --validate --config "$HOME/.config/sway/config" +``` + +La dernière commande nécessite Sway installé. Un lien cassé ou une unité en +échec doit être diagnostiqué avant de considérer la restauration terminée. diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 000000000..de78948c3 --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,64 @@ +# Packages et inventaires + +Les fichiers de `.assets/` sont des snapshots de reconstruction. Ils décrivent +l'état observé ; ils ne garantissent ni l'ordre d'installation ni la présence +des données et projets externes. + +## Inventaires + +| Fichier | Contenu | Source principale | +| --- | --- | --- | +| `.assets/pkglist-pacman.txt` | paquets officiels explicitement installés | `pacman -Qqen` | +| `.assets/pkglist-aur.txt` | paquets foreign/AUR explicitement installés | `pacman -Qqem` | +| `.assets/enabled-services.txt` | services système activés | `systemctl list-unit-files` | +| `.assets/enabled-system-aux-units.txt` | timers, sockets et paths système activés | `systemctl list-unit-files` | +| `.assets/enabled-user-aux-units.txt` | timers, sockets et paths utilisateur activés | `systemctl --user list-unit-files` | +| [`.assets/external-tools.md`](../.assets/external-tools.md) | outils Cargo/npm, builds, projets et helpers locaux | inventaire manuel vérifié | + +## Régénérer les listes de paquets + +Depuis la racine du dépôt, après avoir contrôlé que la machine représente bien +l'état à documenter : + +```bash +pacman -Qqen | LC_ALL=C sort > .assets/pkglist-pacman.txt +pacman -Qqem | LC_ALL=C sort > .assets/pkglist-aur.txt +``` + +`pkglist-aur.txt` signifie techniquement « paquets étrangers à la base de +données sync ». Il peut contenir un paquet construit localement et pas +nécessairement publié dans l'AUR. Chaque entrée doit donc être examinée. + +## Régénérer les snapshots systemd + +```bash +systemctl list-unit-files --type=service --state=enabled \ + --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort + +systemctl list-unit-files --type=socket,path,timer --state=enabled \ + --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort + +systemctl --user list-unit-files --type=socket,path,timer --state=enabled \ + --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort +``` + +Comparer d'abord la sortie aux fichiers versionnés. Certaines unités +instanciées ou activations liées à la machine peuvent demander une revue +manuelle ; ne pas remplacer un inventaire uniquement parce qu'une commande +instantanée diffère. + +## Restaurer avec discernement + +Les listes peuvent aider à préparer une commande Pacman, mais le dépôt ne +promet pas une restauration non interactive. Sur une machine neuve : + +1. restaurer d'abord la base système via `arch-system` ; +2. examiner les paquets officiels encore voulus ; +3. reconstruire les paquets étrangers avec une source AUR ou locale vérifiée ; +4. restaurer séparément les outils Cargo/npm de + [`.assets/external-tools.md`](../.assets/external-tools.md) ; +5. reconstruire ou cloner les projets externes à leurs chemins attendus ; +6. vérifier les exécutables référencés par Sway, Zsh, les scripts et systemd. + +Les credentials, bases applicatives et caches ne doivent jamais être ajoutés +aux inventaires de paquets. diff --git a/docs/recovery.md b/docs/recovery.md new file mode 100644 index 000000000..485727e88 --- /dev/null +++ b/docs/recovery.md @@ -0,0 +1,113 @@ +# Recovery — reconstruire ArchASP + +> **Question :** mon SSD meurt aujourd'hui. Comment reconstruire ArchASP ? + +Les deux dépôts reconstruisent la configuration déclarative, pas l'intégralité +des données personnelles. Une sauvegarde séparée reste indispensable pour les +secrets, bases, documents et états applicatifs. + +## 1. Installer un Arch Linux minimal + +Créer le système de fichiers, installer le système de base et obtenir un +environnement démarrable avec réseau. Cette phase ne relève pas de +`Dotfiles_ArchAP`. + +## 2. Restaurer `arch-system` + +Cloner le dépôt système et suivre sa procédure pour le boot, le stockage, le +réseau, les paquets fondamentaux, `/etc`, greetd, les services système et les +helpers root. Ne pas copier simplement `.assets/greetd/config.toml` sans suivre +le contrat système. + +## 3. Restaurer `Dotfiles_ArchAP` + +Cloner l'upstream Forgejo ou, s'il est indisponible, le miroir GitHub : + +```bash +git clone --recurse-submodules \ + https://github.com/labfytools/Dotfiles_ArchAP.git \ + "$HOME/.dotfiles" +cd "$HOME/.dotfiles" +git switch 0.1.0 +git submodule update --init --recursive +``` + +La branche `0.1.0` donne le snapshot stable ; `main` est la branche de +développement. + +## 4. Restaurer les paquets officiels + +Comparer `.assets/pkglist-pacman.txt` avec le socle déjà installé par +`arch-system`. Installer uniquement les entrées encore pertinentes et éviter +de transformer une capture historique en commande aveugle. + +## 5. Restaurer les paquets AUR/foreign + +Examiner chaque entrée de `.assets/pkglist-aur.txt`, retrouver sa source et la +reconstruire avec un processus AUR maîtrisé. Les paquets locaux ou disparus +exigent une décision spécifique ; aucun helper AUR n'est supposé magique. + +## 6. Déployer Stow + +Suivre le [guide d'installation](installation.md) : définir explicitement les +31 packages, exécuter le dry-run, résoudre les conflits, puis seulement lancer +le déploiement réel. `docs/` et `.assets/` ne sont pas déployés. + +## 7. Restaurer les services + +- recharger et vérifier `systemd --user` ; +- confirmer les liens d'activation versionnés ; +- ne démarrer les unités de projets externes qu'après restauration de leurs + exécutables et configurations ; +- restaurer les services système à partir d'`arch-system`, en utilisant les + snapshots `.assets/enabled-*.txt` comme contrôle croisé. + +## 8. Restaurer les projets externes + +Cloner ou reconstruire les projets et outils listés dans +[`external-tools.md`](../.assets/external-tools.md), notamment Trainlog, +Lardon, Arch Sentinel et les outils 3D locaux. Recréer leurs builds et liens +utilisateur selon leurs propres instructions. Le dépôt de dotfiles ne contient +pas leur code. + +## 9. Restaurer les secrets et données + +Depuis une sauvegarde chiffrée et hors Git, restaurer selon le besoin : + +- identités SSH et GPG ; +- clé et store Atuin locaux ; +- credentials Rclone, GitHub CLI, Nextcloud et applications ; +- bases Trainlog et autres données applicatives ; +- documents personnels et états non reconstructibles. + +Ne copier aucun de ces éléments dans le dépôt. Vérifier leurs permissions +avant de lancer les applications. + +## 10. Valider + +```bash +git -C "$HOME/.dotfiles" status --short +git -C "$HOME/.dotfiles" submodule status --recursive +find "$HOME" -xtype l -print +systemctl --failed +systemctl --user --failed +sway --validate --config "$HOME/.config/sway/config" +``` + +Contrôler ensuite le login greetd/tuigreet, le démarrage UWSM/Sway, Swaybar, +i3status-rs, les notifications, le verrouillage, le presse-papiers, Kitty et +un nouveau shell Zsh. + +## Limites actuelles + +Une reconstruction à partir des seuls dépôts ne restitue pas : + +- secrets, historiques et bases applicatives ; +- contenu des projets sous `~/Documents` ; +- builds locaux, outils Cargo/npm et OpenMVS ; +- helpers `/usr/local` si `arch-system` ne les recrée pas encore ; +- réglages matériels spécifiques non documentés ; +- paquets AUR disparus ou devenus incompatibles. + +La récupération est donc **documentée et largement reproductible**, mais pas +une image complète et autonome du disque. diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 000000000..124f9f3fa --- /dev/null +++ b/docs/security.md @@ -0,0 +1,69 @@ +# Sécurité + +## Politique de versionnement + +Ne jamais versionner, même temporairement : + +- clés Atuin et bases/store Atuin ; +- clés privées SSH ; +- clés privées GPG ; +- tokens et clés API ; +- mots de passe et cookies ; +- `.netrc` ; +- credentials Rclone ; +- credentials GitHub ou Forgejo ; +- secrets Nextcloud ; +- credentials Proton, WireGuard ou autres applications ; +- bases applicatives et historiques personnels. + +Un `.gitignore` limite les erreurs courantes, mais ne constitue pas une +protection suffisante. Avant chaque publication, inspecter le diff, les +nouveaux fichiers et les motifs de credentials sans jamais afficher leur +valeur dans un rapport. + +## Stockage local + +Les secrets et données runtime appartiennent à la machine locale ou à une +sauvegarde chiffrée externe. Ils ne doivent pas être placés dans un package +Stow public. Les permissions doivent être restrictives, particulièrement pour +les clés privées, `.netrc`, stores de credentials et clé Atuin. + +Les unités ou scripts peuvent référencer le chemin d'une configuration locale, +mais ne doivent ni embarquer son contenu ni journaliser ses secrets. + +## Historique Git + +Supprimer un fichier du dernier commit ne le retire pas des anciens objets +Git. Lorsqu'un secret a été commité, la réponse correcte est : + +1. considérer le secret comme compromis ; +2. le révoquer ou le faire tourner ; +3. préserver les sauvegardes nécessaires hors dépôt ; +4. purger le chemin de tout l'historique ; +5. vérifier les objets et toutes les refs avant publication. + +L'historique de `Dotfiles_ArchAP` a été assaini pendant la préparation de la +version `0.1.0`, notamment pour retirer les anciennes données locales qui ne +devaient pas être publiées. Cette mention ne révèle ni ancienne valeur, ni +empreinte sensible, ni emplacement de sauvegarde. + +## Contrôles avant publication + +```bash +git status --short +git diff --check +git diff --cached --check +git fsck --full --no-dangling +``` + +Compléter ces contrôles par une recherche prudente de types de secrets dans le +HEAD et l'historique. Les rapports doivent seulement indiquer le fichier, le +type potentiel, sa présence actuelle ou historique et l'action recommandée ; +ils ne doivent jamais reproduire la valeur détectée. + +## Dépôt public et licence + +Le miroir GitHub est public. Toute donnée commitée doit donc être considérée +comme publiable immédiatement. Le dépôt ne possède actuellement aucune +licence ; cette absence n'autorise pas implicitement la réutilisation du +contenu. diff --git a/docs/shell.md b/docs/shell.md new file mode 100644 index 000000000..2e55b298c --- /dev/null +++ b/docs/shell.md @@ -0,0 +1,77 @@ +# Shell + +## Chaîne interactive + +```mermaid +flowchart LR + Z[Zsh] --> S[Starship] + Z --> A[Atuin] + Z --> F[FZF] + Z --> X[Zoxide] + Z --> E[Eza] + Z --> B[Bat] + Z --> Y[Yazi] +``` + +| Élément | Rôle | +| --- | --- | +| Zsh | shell interactif et point d'intégration | +| Starship | prompt configuré par `starship/.config/starship.toml` | +| Atuin | recherche d'historique local ; base et clé exclues de Git | +| FZF | sélection interactive et prévisualisations | +| Zoxide | navigation par fréquence | +| Eza | affichage enrichi des répertoires | +| Bat | lecture et prévisualisation colorée | +| Yazi | gestionnaire de fichiers terminal | + +`.zprofile` initialise la session graphique via UWSM lorsque son contexte le +permet. `.zshenv` publie le socket de l'agent SSH utilisateur. `.zshrc` charge +les intégrations interactives, aliases et fonctions. + +## Plugins Zsh et Tmux + +Les plugins ne sont pas téléchargés à chaque ouverture du shell. Git épingle +leurs commits comme sous-modules : + +| Intégration | Chemin versionné | +| --- | --- | +| Fast Syntax Highlighting | `zsh/.zsh/plugins/fast-syntax-highlighting` | +| FZF Tab | `zsh/.zsh/plugins/fzf-tab` | +| Zsh Autosuggestions | `zsh/.zsh/plugins/zsh-autosuggestions` | +| Catppuccin Tmux | `tmux/.config/tmux/plugins/catppuccin/tmux` | + +Initialisation et contrôle : + +```bash +git submodule update --init --recursive +git submodule status --recursive +``` + +La configuration Zsh vérifie la lisibilité des fichiers de plugins avant de +les sourcer. Le dépôt parent, et non une commande lancée au démarrage du shell, +reste propriétaire des versions. + +## Scripts utilisateur + +Le package `bin` déploie des commandes dans `~/.local/bin`. Les familles +principales sont : + +- maintenance Pacman/AUR (`aurinstall`, `aurremove`, `aursearch`, `aurupdate`) ; +- énergie et batterie (`batlimit`, `battery-low-notify.sh`, `tlp-profile.sh`) ; +- session et applications (`sway-close`, `thunderbird-proton`, + `vmware-on-demand`, `nextcloud-sync`) ; +- développement local (`dcnvim`, `goose`, `pi-dev`, `opencode-away`) ; +- acquisition/3D (`colmap-amd`, `scan3d`, `scan3d-watch`) ; +- intégrations Trainlog (`trainlog-bt-watch`) et autres projets locaux. + +Ces scripts orchestrent des outils existants ; ils ne fournissent pas les +projets externes, credentials ou binaires système qu'ils appellent. Consulter +[`external-tools.md`](../.assets/external-tools.md) avant de les réutiliser sur +une autre machine. + +## Données locales + +L'historique Zsh et le store Atuin sont des données utilisateur, pas de la +configuration. La clé, la base, les sessions et tout identifiant Atuin restent +hors Git. Cette installation utilise Atuin localement ; aucune procédure de +compte ou de synchronisation distante n'est requise par le dépôt. diff --git a/docs/systemd.md b/docs/systemd.md new file mode 100644 index 000000000..ba6d9f874 --- /dev/null +++ b/docs/systemd.md @@ -0,0 +1,63 @@ +# systemd + +## Deux périmètres distincts + +| Périmètre | Commande | Propriété | +| --- | --- | --- | +| système | `systemctl ...` | `arch-system`, `/etc/systemd/system`, services root | +| utilisateur | `systemctl --user ...` | package Stow `systemd`, `~/.config/systemd/user` | + +Le dépôt conserve dans `.assets/enabled-services.txt` et +`.assets/enabled-system-aux-units.txt` des snapshots de la couche système, +mais il ne l'active pas. Les unités effectivement versionnées sous +`systemd/.config/systemd/user/` appartiennent à la couche utilisateur. + +## Unités utilisateur canoniques + +| Domaine | Unités | Fonction | +| --- | --- | --- | +| session | `gnome-keyring-daemon.service`, `ssh-agent.service`, `wlsunset.service` | agents et services de session | +| clipboard | `cliphist-text.service`, `cliphist-image.service` | collecte texte et images Wayland | +| idle | `swayidle.service` | verrouillage, alimentation des sorties et pause média | +| batterie | `battery-low-notify.service/.timer` | contrôle et notification périodiques | +| maintenance | `clean-makepkg.service` | nettoyage du cache temporaire utilisateur | +| Arch Sentinel | `arch-sentinel-sample.service/.timer` | collecte périodique légère | +| Trainlog | `trainlog-btd.service`, `trainlog-syncd.service`, `trainlog-web.service` | intégrations locales facultatives | +| Lardon | `lardon-freecad.service` | session FreeCAD liée au projet externe | +| autres | `hyprwhspr.service`, `protonmail-bridge.service` | intégrations déclenchées selon l'usage | + +Les liens versionnés dans `default.target.wants/`, +`graphical-session.target.wants/` et `timers.target.wants/` expriment les +activations utilisateur retenues. `.assets/enabled-user-aux-units.txt` capture +en complément les timers et sockets activés observés sur la machine. + +## Dépendances externes + +Les unités Trainlog, Lardon et Arch Sentinel supposent que leurs projets ou +binaires existent aux chemins décrits dans +[`external-tools.md`](../.assets/external-tools.md). +Certaines unités Trainlog sont conditionnées par une configuration locale. +Ces fichiers de configuration et leurs éventuels secrets ne sont pas +versionnés. + +Une unité absente du projet externe peut rester valide syntaxiquement tout en +échouant à l'exécution. La restauration doit donc vérifier à la fois le fichier +d'unité et son `ExecStart`. + +## Validation + +Après déploiement Stow : + +```bash +systemctl --user daemon-reload +systemd-analyze --user verify \ + "$HOME"/.config/systemd/user/*.service \ + "$HOME"/.config/systemd/user/*.timer +systemctl --user list-unit-files --state=enabled +systemctl --user --failed +``` + +Ne pas lancer ou activer en bloc toutes les unités : celles liées à des +projets externes sont facultatives et peuvent exiger une configuration locale. +Les modifications des services système se font dans `arch-system`, jamais par +une commande `systemctl` non documentée dans ce dépôt.