diff --git a/docs/debian-13-migration-plan.md b/docs/debian-13-migration-plan.md new file mode 100644 index 0000000..a2ac7fb --- /dev/null +++ b/docs/debian-13-migration-plan.md @@ -0,0 +1,137 @@ +# Debian 13 ("trixie") Migration Plan + +Goal: make this dotfiles repo fully suited for **Debian 13 (trixie)** so a fresh Debian install can be brought up to the same state as the current Fedora setup. + +Working branch: `debian-13` (base: `master`). + +--- + +## 1. Summary of what changes + +The repo is mostly distro-agnostic already (shell rc files, aliases, nvim via NvChad + Mason, Flatpak list, GitHub-downloaded dev tools). The Fedora coupling is concentrated in: + +1. **Package manager + detection** (`main-setup.sh`, scripts 00/01) — mostly *works* for Debian already since detection returns `debian` → `apt`, but package *names* and repos differ. +2. **Fedora-only .NET script** (`03-fedora-dotnet-setup.sh`) — needs a distro-agnostic (or Debian-specific) counterpart. +3. **README + comments** referencing Fedora-only steps/groups. +4. Several **Debian 13 gotchas** (PEP 668 pip, `dnsutils` → `bind9-dnsutils`, `bat` → `batcat`, missing upstream-only tools like `kubectl`/`gh`/`terraform`/`minikube`/`k9s`, `sudo` not always present, Microsoft repo for trixie). + +--- + +## 2. Debian 13 facts that drive the changes + +| Topic | Fedora behavior | Debian 13 (trixie) behavior | +|---|---|---| +| Package manager | `dnf` / `rpm -q` | `apt` / `dpkg-query` (already handled) | +| `sudo` | preinstalled | **not always installed** on fresh installs | +| pip | system pip installs OK | **PEP 668** blocks `pip install --user` (`externally-managed-environment`) | +| `dnsutils` | `bind-utils` | package renamed to `bind9-dnsutils` (trixie) | +| `bat` | binary `bat` | package ships **`batcat`**, needs `bat` symlink/alias | +| `fd-find` | binary `fd` | binary **`fdfind`**, script already symlinks | +| `.NET` | MS repo for Fedora + `moby-engine` | MS repo for `debian/13` (`packages-microsoft-prod.deb`) or `dotnet-install.sh` | +| Docker | `moby-engine` | `docker.io` (Debian) or `docker-ce` (Docker repo) | +| PostgreSQL | needs `postgresql-setup --initdb` | cluster auto-created by package scripts | +| `kubectl`/`gh`/`terraform`/`minikube`/`k9s` | in COPR/DNF repos | **not in Debian main** → add upstream apt repos or download `.deb` | +| `chsh` | `util-linux-user` package | in base util-linux; needs password/sudo to change shell | +| libvirt group | `libvirt` | same `libvirt` group (add user) | +| default shell | zsh setup via OhMyZsh scripts | zsh not default; needs `chsh` after install | + +--- + +## 3. File-by-file plan + +### `main-setup.sh` +- [ ] Keep existing `detect_linux_distro()` — already returns `debian` for trixie (`ID=debian`). Verify `sudo` present; if missing, warn to `su -`/install `sudo` first (or auto-detect root). +- [ ] Replace the Fedora-only prompt for `03-fedora-dotnet-setup.sh` with a distro-agnostic `.NET` prompt (new `03-dotnet-setup.sh`), OR gate on both `fedora` and `debian`. +- [ ] Consider exporting `DEBIAN_CODENAME`/`DISTRO_VERSION` (from `/etc/os-release`) for downstream repo URLs. + +### `scripts/00-system-prep.sh` +- [ ] `apt update && apt upgrade` path already correct. Add optional: install `sudo`, `curl`, `gnupg`, `ca-certificates`, `software-properties-common`/`apt-transport-https` prerequisites early. +- [ ] (Optional) enable `contrib`/`non-free-firmware` components in `/etc/apt/sources.list.d/debian.sources` — needed for some firmware/tools. + +### `scripts/01-package-install.sh` +- [ ] Split `BASE_PACKAGE_LIST` into truly-common + distro lists; on Debian drop anything not in trixie and add Debian equivalents. +- [ ] **Rename fixes (Debian branch of `DISTRO_SPECIFIC_PACKAGES`):** + - `dnsutils` → `bind9-dnsutils` + - add `bat` handling: after install, `ln -sf /usr/bin/batcat /usr/local/bin/bat` + - add `sudo`, `ca-certificates`, `gnupg`, `curl` (ensure present) + - add `libvirt-daemon-system`, `virtinst`, `qemu-kvm`, `bridge-utils` for virt-manager + - add `zsh` post: `chsh -s /usr/bin/zsh` (or instruct) + - `python3-pip` stays, but flag PEP 668 handling (see 02) + - `docker.io` + `docker-compose` **or** wire Docker CE repo (defer to decision in §4) +- [ ] **Upstream repo tools not in Debian main** — install in this script or a new `05-` script: + - `gh` → GitHub CLI apt repo (`https://cli.github.com/packages`) + - `terraform` → HashiCorp apt repo + - `kubectl` → Kubernetes apt repo (`pkgs.k8s.io`) + - `k9s`, `minikube` → GitHub `.deb` releases (minikube official `.deb` exists) +- [ ] Flatpak list unchanged (distro-agnostic). Note VS Code Flatpak vs MS repo decision in §4. + +### `scripts/02-dev-tools-setup.sh` +- [ ] **pynvim PEP 668 fix:** replace `pip install --user pynvim` with `python3 -m pip install --user --break-system-packages pynvim`, or (cleaner) install into NvChad's venv, or note `pipx`. +- [ ] Rest is GitHub-download based → distro-agnostic; verify `unzip`, `tar`, `wget` present. +- [ ] `dive` already handles `.deb` via `dpkg -i` on apt — good. +- [ ] Go/Rust/Nerd Font/Oh-My-Posh/Helm/kubectx/stern/trivy/AWS — no changes needed. + +### `scripts/03-fedora-dotnet-setup.sh` → split/generalize +- [ ] Rename to **`03-dotnet-setup.sh`** and branch by `$PACKAGE_MANAGER`: + - **Fedora:** keep existing RPM/MS-repo path. + - **Debian:** add MS Debian repo `https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb` (verify trixie support; fall back to `dotnet-install.sh` if repo is unavailable for trixie) then `apt install dotnet-sdk-10.0` (or 8/9 fallback loop like Fedora). + - Alternatively use official **`dotnet-install.sh`** for both — fully distro-agnostic, no repo dependency. +- [ ] Replace Fedora-specific db/container section with Debian equivalents: + - PostgreSQL: `apt install postgresql` (cluster auto-init — remove `postgresql-setup --initdb` step for Debian; just `systemctl enable --now postgresql`). + - Docker: `docker.io` + `docker-compose` + add user to `docker` group, or Docker CE repo. +- [ ] Update `main-setup.sh` gate accordingly. + +### `scripts/04-config-symlinks.sh` +- [ ] No functional changes needed (pure symlinking). Optionally handle `~/.bash_aliases` (Debian's default bashrc sources it) or leave as-is since `bashrc` sources `aliases.bash` directly. + +### Shell rc files (`bashrc`, `zshrc`, aliases) +- [ ] Already distro-agnostic (PATH for `/usr/local/go`, `~/.local/bin`, cargo, nvm). No Fedora-specific bits. +- [ ] Note: `zshrc` still references **oh-my-zsh** (`$ZSH/oh-my-zsh.sh`, `plugins=(git)`) but no script installs it anymore (repo moved to Oh-My-Posh). On a fresh Debian this will fail silently. Decide: purge oh-my-zsh remnants or restore its install step. Recommend purging on this branch. +- [ ] Ensure `~/.fzf.zsh` / `~/.fzf.bash` generation (`fzf --zsh`/`--bash`) or skip gracefully (already guarded). + +### `README.md` +- [ ] Update "Supported Distributions" / feature matrix to reflect **Debian 13 = first-class**, Fedora optional. +- [ ] Rename "Fedora-Specific (.NET)" section → ".NET Development" with per-distro notes. +- [ ] Update post-install steps (group names `docker`, `libvirt`; remove Fedora-only log-out note if not applicable; add PEP 668 note). +- [ ] Update file listing for `03-*.sh` renames. + +--- + +## 4. Open decisions (need your input) + +1. **Container runtime on Debian:** `docker.io` (Debian pkg) vs official **Docker CE** repo vs **Podman** (since Fedora used Podman Desktop + `moby-engine`)? This repo mixes docker aliases and Podman Desktop flatpak. +2. **VS Code source:** keep **Flatpak** `com.visualstudio.code` (already in list) or switch to MS apt repo `.deb` like Fedora's RPM setup did? +3. **.NET SDK version to target:** repo tries 8.0 → 9.0 on Fedora; pick a default for Debian (e.g. SDK 10 on trixie) or keep the fallback loop. +4. **oh-my-zsh remnants in `zshrc`:** purge (recommended) or keep? +5. **Scope of this branch:** full rework of all scripts, or a lighter pass (fix names + PEP 668 + .NET script) to validate on a live trixie box first? + +--- + +## 5. Suggested execution order + +1. Do the cheap, high-confidence fixes: + - `main-setup.sh` gating + `.NET` prompt + - `01-package-install.sh` Debian package renames (`bind9-dnsutils`, `bat` symlink, prerequisites, virt stack) + - `02-dev-tools-setup.sh` PEP 668 pynvim fix +2. Rename/generalize `03-fedora-dotnet-setup.sh` → `03-dotnet-setup.sh`. +3. Add upstream repo/bootstrap logic for `gh`, `terraform`, `kubectl`, `minikube`, `k9s`. +4. Purge oh-my-zsh remnants from `zshrc`. +5. Update `README.md`. +6. Test end-to-end on a Debian 13 VM (or real install) before merging to `master`. + +--- + +## 6. Verification checklist (on Debian 13) + +```bash +# sanity +cat /etc/os-release # expect ID=debian, VERSION_CODENAME=trixie +./main-setup.sh # expect "Using Package Manager: apt" +bat --version # symlink check +fd --version # symlink check +dig example.com # bind9-dnsutils +python3 -m pip install --user pynvim # must not hit PEP 668 error +dotnet --list-sdks +docker ps # group membership +virsh list # libvirt group +```