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

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

scripts/00-system-prep.sh — DONE

• sudo bootstrap when running as root on a fresh install (apt/dnf).
• 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

• 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).
• 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.
• Kubernetes minor auto-detected from the latest k8s release (fallback v1.36; override with K8S_MINOR).
• Flatpak list unchanged (VS Code stays Flatpak per decision).

scripts/02-dev-tools-setup.sh — DONE

• 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

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

scripts/04-config-symlinks.sh — no changes required

• Pure symlinking; distro-agnostic as-is.

Shell rc files (bashrc, zshrc, aliases) — DONE

• zshrc oh-my-zsh remnants purged (plain zsh + Oh-My-Posh).
• Duplicate Go PATH lines (appended by an old 02 run) removed from bashrc/zshrc.
• nvim/nvim + nushell/nushell self-symlink targets updated to /home/blake.

README.md — DONE

• 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)

• 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.
• 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)

# 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