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

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