dotfiles/docs/debian-13-migration-plan.md

# 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`).

> **Status: implemented on this branch** (see `git log` on `debian-13`). Recorded decisions below.

### Decisions (user-confirmed)
1. **Container runtime:** Podman (`podman`, `podman-compose`, `podman-docker` shim) — no Docker CE / moby-engine.
2. **VS Code:** keep the **Flatpak** install (`com.visualstudio.code`); no MS apt/rpm repo for the editor.
3. **.NET install:** official **`dotnet-install.sh`** (channel `STS`, overridable via `DOTNET_CHANNEL`) — no Microsoft vendor repo.
4. **oh-my-zsh:** **purge** its remnants from `zshrc` (now plain zsh + Oh-My-Posh).
5. **Scope:** **full rework** applied to `main-setup.sh` and all `scripts/*.sh`, `zshrc`, `README.md`.

---

## 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 status (as of 2026-09-02)

### `main-setup.sh` — DONE
- [x] `detect_linux_distro()` returns `debian` for trixie; `PACKAGE_MANAGER=apt`.
- [x] Preflight: if non-root and `sudo` missing → clear guidance (run as root or install `sudo`); `sudo -n` note.
- [x] `.NET` prompt is now distro-agnostic → runs `03-dotnet-setup.sh` on every supported distro.

### `scripts/00-system-prep.sh` — DONE
- [x] `sudo` bootstrap when running as root on a fresh install (apt/dnf).
- [x] Debian: idempotently add `contrib` + `non-free-firmware` to `debian.sources` (deb822) or legacy `sources.list` (skip with `SKIP_NONFREE=1`); `needrestart` installed on apt.

### `scripts/01-package-install.sh` — DONE
- [x] Split base vs distro lists; `dnsutils` → `bind9-dnsutils`; `bat` → `batcat` symlink; libvirt/QEMU stack (`libvirt-daemon-system`, `libvirt-clients`, `qemu-system-x86`, `virtinst`, `bridge-utils`); prereqs (`sudo`, `ca-certificates`, `gnupg`, `curl`).
- [x] `setup_upstream_tooling()`: vendor repos for `gh` (GitHub CLI), `terraform` (HashiCorp), `kubectl` (pkgs.k8s.io); `k9s` (GitHub tarball) + `minikube` (official `.deb`) on apt; best-effort `dnf` on Fedora.
- [x] Kubernetes minor auto-detected from the latest k8s release (fallback `v1.36`; override with `K8S_MINOR`).
- [x] Flatpak list unchanged (VS Code stays Flatpak per decision).

### `scripts/02-dev-tools-setup.sh` — DONE
- [x] `pynvim` PEP 668 fix: try `pip install --user`, fall back to `--break-system-packages`.

### `scripts/03-fedora-dotnet-setup.sh` → `03-dotnet-setup.sh` — DONE
- [x] Renamed to `03-dotnet-setup.sh`, distro-agnostic (apt/dnf).
- [x] `.NET SDK` via official `dotnet-install.sh` (channel `STS`, override `DOTNET_CHANNEL`) → `~/.dotnet`, PATH added to `bashrc`/`zshrc`.
- [x] PostgreSQL: auto-cluster on Debian; `--initdb` only on Fedora.
- [x] Containers = **Podman** + `podman-compose` + `podman-docker` (Docker-CLI shim). No MS repo, no moby/docker-ce.

### `scripts/04-config-symlinks.sh` — no changes required
- [x] Pure symlinking; distro-agnostic as-is.

### Shell rc files (`bashrc`, `zshrc`, aliases) — DONE
- [x] `zshrc` oh-my-zsh remnants purged (plain zsh + Oh-My-Posh).
- [x] Duplicate Go `PATH` lines (appended by an old 02 run) removed from `bashrc`/`zshrc`.
- [x] `nvim/nvim` + `nushell/nushell` self-symlink targets updated to `/home/blake`.

### `README.md` — DONE
- [x] Debian 13 first-class; feature lists, modular architecture, post-install steps, and supported-distro matrix updated (Podman, Flatpak VS Code, libvirt/kvm groups, rootless podman socket).

### Tooling / quality — DONE (this pass)
- [x] **`scripts/verify-debian.sh`** added — non-destructive end-to-end sanity checker (OS, binaries, Debian renames, upstream tools, dev tools, .NET/Podman/Postgres, groups, flatpak, dotfile symlinks); exit code 0/1.
- [x] **ShellCheck** (v0.11.0) run on all scripts — clean at warning severity (remaining notes are pre-existing info/style only).

---

## 4. Decisions (confirmed)
1. **Container runtime:** Podman (`podman-docker` provides the `docker` shim so existing aliases keep working).
2. **VS Code:** Flatpak `com.visualstudio.code` (no MS editor repo).
3. **.NET:** official `dotnet-install.sh` (no MS vendor repo).
4. **oh-my-zsh:** purged from `zshrc`.
5. **Scope:** full rework (applied).

## 5. Remaining work / next steps
- [ ] **Test end-to-end on a real Debian 13 box**: run `./main-setup.sh`, then `bash scripts/verify-debian.sh`, and fix anything the checker flags.
- [ ] Decide whether to keep Fedora/dnf support long-term or trim it later (kept for now).
- [ ] Merge `debian-13` → `master` after validation.

---

## 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
```