Skip to content
SYNNET DevHub

ADR 001 — Debian 13 as Base OS

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/decisions/001-debian-12-as-base-os.md. Edit at the source, not here.

ADR 001 — Debian 13 as Base OS

Section titled “ADR 001 — Debian 13 as Base OS”

Status: Accepted Date: 2026-04-19 Deciders: SYNNET Engineering

Context

Section titled “Context”

SynVirt requires a stable, well-supported Linux base operating system that:

  • Ships with a modern, stable kernel with KVM and QEMU support out of the box
  • Has a mature package ecosystem for the tools we depend on (libvirt, DRBD, ZFS DKMS, nftables, OVN)
  • Supports fully automated, unattended installation via ISO preseed
  • Is widely familiar to sysadmins in Mexico and LATAM
  • Provides a long support window to minimize forced OS upgrades in production
  • Exposes a recent enough kernel series that modern storage stacks (including OpenZFS 2.4.x from backports) can be deployed without locally compiling a kernel

Decision

Section titled “Decision”

Use Debian 13 Trixie minimal as the base OS for the SynVirt appliance ISO. The ISO is built from the Debian 13 netinstall image (13.4.0, amd64) via a custom preseed configuration that automates partitioning, package selection, and post-install setup. OpenZFS 2.4.x is sourced from trixie-backports (see ADR 010).

Rationale

Section titled “Rationale”
  • LTS support: Debian 13 has a 5-year security support window and LTS coverage that extends into the 2030s. This aligns with the expected production lifetime of SynVirt appliances.
  • Kernel 6.12 LTS: Trixie ships Linux 6.12 LTS, a long-term branch with a support window that spans the full SynVirt 0.x → 1.x roadmap. This kernel series is required by OpenZFS 2.4.x and by the newer KVM features we rely on.
  • KVM/QEMU ecosystem: Debian ships qemu-kvm, libvirt-daemon, and related tools in its standard repositories. No third-party repos are required for the hypervisor core.
  • Hardware support: Debian’s kernel includes broad hardware support for server-class hardware common in Mexican SMB deployments (Intel/AMD servers, common RAID controllers, mainstream NICs).
  • Preseed automation: Debian’s installer has first-class preseed support, enabling fully unattended installation from a single boot. This is critical for our ISO builder workflow.
  • Sysadmin familiarity: Debian (and its derivatives) are the most widely deployed Linux distributions among LATAM sysadmins and MSPs. Support staff can work with the OS without retraining.
  • ZFS/DRBD DKMS: Both OpenZFS and DRBD ship DKMS packages in Debian’s repositories (OpenZFS via trixie-backports), simplifying storage integration in Hito 0.3+ and Hito 2.

Consequences

Section titled “Consequences”
  • Must maintain a custom ISO builder. We cannot ship a stock Debian ISO; the builder must be maintained as the project evolves and as Debian point releases land.
  • Package ecosystem is Debian-only. Tools not in the Debian repositories must be installed manually or packaged as .deb files.
  • Kernel upgrade discipline required. When ZFS and DRBD DKMS modules are in use (Hito 0.3+), kernel upgrades must be tested to verify DKMS rebuilds succeed before the upgrade is applied to production nodes.
  • Root filesystem is ext4 until Hito 3. The root partition uses ext4 at a fixed 40 GB size. ZFS is used for the secondary pool (localdata) only in Hito 0.3 onward. ZFS-on-root and boot environments are deferred to Hito 3 (see ADR 003 and Issue 001).

Alternatives Considered

Section titled “Alternatives Considered”

Ubuntu Server 24.04 LTS

Section titled “Ubuntu Server 24.04 LTS”
  • Pros: Large community, commercial support options, familiar to many.
  • Cons: More frequent release cycles create upgrade pressure. snap package management introduces complexity in minimal server installs. LTS releases sometimes ship newer packages that introduce unexpected regressions.
  • Decision: Rejected in favor of Debian’s more conservative, predictable release cadence.

Enterprise-Linux derivative (RPM-based rebuild)

Section titled “Enterprise-Linux derivative (RPM-based rebuild)”
  • Pros: Binary-compatible with a widely-used enterprise Linux ecosystem, popular in traditional enterprise environments.
  • Cons: The RPM + dnf + default mandatory-access-control ecosystem is less familiar to the LATAM sysadmin community we target. DRBD and ZFS packages require extra third-party repositories. The automated installer equivalent (kickstart) is workable but the Debian ecosystem has significantly more tooling and community material around preseed.
  • Decision: Rejected. The RPM-based ecosystem introduces more friction than benefit for our target market.

NixOS

Section titled “NixOS”
  • Pros: Reproducible builds, declarative configuration, excellent for infrastructure-as-code.
  • Cons: Too niche for the SMB/MSP target market. Support staff unfamiliar with the Nix ecosystem would struggle with operational tasks. The learning curve is prohibitive for customers and support engineers alike.
  • Decision: Rejected. Architectural elegance cannot outweigh operational familiarity for a commercial product targeting SMBs.

Debian 12 Bookworm (the prior base)

Section titled “Debian 12 Bookworm (the prior base)”
  • Pros: Previously selected; proven with the Hito 0.1/0.2 ISO builder.
  • Cons: Kernel 6.1 LTS on Bookworm does not track the newer KVM and OpenZFS improvements we want to baseline on. Trixie provides kernel 6.12 LTS, which is required to cleanly run OpenZFS 2.4.x from backports and the KVM features planned for Hito 1.
  • Decision: Superseded. The 0.3 milestone moves the base to Trixie; see ADR 008 for the migration record.