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

# 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