path: root/docs/PLAN-archangel-btrfs.org

#+TITLE: Implementation Plan: Archangel Btrfs Support
#+DATE: 2026-01-23

* Overview

Add btrfs filesystem support to archangel (formerly archzfs) installer.
Users can choose ZFS or Btrfs during installation.

See [[file:research-btrfs-expansion.org][research-btrfs-expansion.org]] for background research.

* Key Decisions (Already Made)

- Project rename: archzfs → archangel
- Snapshot tool: snapper + snap-pac + grub-btrfs
- Bootloader: ZFS uses ZFSBootMenu, Btrfs uses GRUB
- Encryption: ZFS native, Btrfs uses LUKS
- RAID: Btrfs raid1 only (raid5/6 unstable)
- Layout: Btrfs subvols mirror ZFS datasets

* Phase 1: Refactor Current Installer

Goal: Modularize install-archzfs before adding btrfs.

** 1.1 Create lib/ directory structure
- [ ] Create custom/lib/ directory
- [ ] Move color/output functions → lib/common.sh
- [ ] Move fzf prompt functions → lib/common.sh
- [ ] Move config file handling → lib/config.sh

** 1.2 Extract ZFS-specific code
- [ ] Create lib/zfs.sh
- [ ] Move pool creation → lib/zfs.sh
- [ ] Move dataset creation → lib/zfs.sh
- [ ] Move ZFS mount logic → lib/zfs.sh
- [ ] Move ZFSBootMenu install → lib/zfs.sh

** 1.3 Extract shared disk operations
- [ ] Create lib/disk.sh
- [ ] Move partitioning logic (EFI + root)
- [ ] Move disk selection/validation
- [ ] Move RAID detection logic

** 1.4 Add filesystem selection prompt
- [ ] Add fzf prompt: "Filesystem: ZFS / Btrfs"
- [ ] Store choice in config
- [ ] Gate ZFS vs Btrfs code paths

** 1.5 Rename project
- [ ] Rename install-archzfs → archangel
- [ ] Update build.sh references
- [ ] Update README.org
- [ ] Update all internal references

* Phase 2: Implement Btrfs Support

Goal: Full btrfs installation path.

** 2.1 Create lib/btrfs.sh
- [ ] Create btrfs volume function
- [ ] Create subvolume creation function
- [ ] Create mount function (with correct options)
- [ ] Create fstab generation (NO subvolid!)

** 2.2 Subvolume layout
Create these subvolumes (matching ZFS datasets):
- [ ] @ → /
- [ ] @home → /home
- [ ] @snapshots → /.snapshots (snapper requirement)
- [ ] @var_log → /var/log
- [ ] @var_cache → /var/cache
- [ ] @tmp → /tmp
- [ ] @var_tmp → /var/tmp
- [ ] @media → /media (compress=off)
- [ ] @vms → /vms (nodatacow)
- [ ] @var_lib_docker → /var/lib/docker

** 2.3 Mount options
#+BEGIN_SRC
BTRFS_OPTS="noatime,compress=zstd,space_cache=v2,discard=async"
#+END_SRC
- [ ] Apply to all subvols except @media (compress=off) and @vms (nodatacow)

** 2.4 Snapper configuration
- [ ] Install snapper, snap-pac packages
- [ ] Create /etc/snapper/configs/root
- [ ] Set timeline policy (hourly=6, daily=7, weekly=2, monthly=1)
- [ ] Enable snapper-timeline.timer
- [ ] Enable snapper-cleanup.timer

** 2.5 GRUB + grub-btrfs installation
- [ ] Install grub, grub-btrfs packages
- [ ] Configure GRUB for btrfs root
- [ ] Enable grub-btrfsd service (auto-update on snapshots)
- [ ] Test snapshot appears in GRUB menu

** 2.6 Genesis snapshot
- [ ] Create initial snapshot: snapper create -d "genesis"
- [ ] Verify appears in snapper list
- [ ] Verify appears in GRUB menu

** 2.7 LUKS encryption (optional)
- [ ] Add encryption prompt (yes/no)
- [ ] Create LUKS container on root partition
- [ ] Configure crypttab
- [ ] Add encrypt hook to mkinitcpio
- [ ] Test passphrase prompt at boot

* Phase 3: Multi-disk Btrfs

Goal: Mirror support for btrfs.

** 3.1 Btrfs RAID1 creation
- [ ] Detect multi-disk selection
- [ ] Create raid1 volume: mkfs.btrfs -d raid1 -m raid1 /dev/sdX /dev/sdY
- [ ] Handle 2+ disk configurations

** 3.2 EFI redundancy
- [ ] Create EFI partition on all disks
- [ ] Install GRUB to all EFI partitions
- [ ] Create boot entries for each disk

** 3.3 Degraded boot support
- [ ] Add degraded mount option for emergency
- [ ] Document recovery procedure

* Phase 4: Testing Infrastructure

Goal: Automated tests for all configurations.

** 4.1 Test configs
- [ ] Create test-configs/zfs-single.conf
- [ ] Create test-configs/zfs-mirror.conf
- [ ] Create test-configs/btrfs-single.conf
- [ ] Create test-configs/btrfs-mirror.conf
- [ ] Create test-configs/btrfs-encrypted.conf

** 4.2 Test scripts
- [ ] Create test-btrfs-single.sh
- [ ] Create test-btrfs-mirror.sh
- [ ] Update test-vm.sh for btrfs option

** 4.3 Validation checks (per research doc)
- [ ] Fresh install checks
- [ ] Reboot survival checks
- [ ] Snapshot operation checks
- [ ] Rollback + reboot checks
- [ ] Failure recovery checks (multi-disk)
- [ ] Encryption checks

* Phase 5: CLI Tools

Goal: Unified snapshot management wrappers.

** 5.1 archangel-snapshot
- [ ] Detect filesystem (ZFS vs Btrfs)
- [ ] ZFS: call zfs snapshot
- [ ] Btrfs: call snapper create
- [ ] Consistent interface for both

** 5.2 archangel-rollback
- [ ] Detect filesystem
- [ ] ZFS: call zfsrollback script
- [ ] Btrfs: call snapper rollback
- [ ] Include reboot prompt (required for full rollback)

** 5.3 archangel-list
- [ ] List snapshots for either filesystem
- [ ] Consistent output format

* Phase 6: Documentation

Goal: Update all docs for dual-filesystem support.

** 6.1 README.org
- [ ] Update project name to archangel
- [ ] Document filesystem choice
- [ ] Update feature list
- [ ] Update usage examples

** 6.2 RESCUE-GUIDE.txt
- [ ] Add btrfs recovery procedures
- [ ] Add snapper commands
- [ ] Add GRUB recovery for btrfs

** 6.3 New docs
- [ ] Create BTRFS.org with btrfs-specific details
- [ ] Update NOTES.org project context

* Schedule (Suggested Order)

1. Phase 1 (Refactor) - do first, enables everything else
2. Phase 2 (Btrfs single-disk) - core functionality
3. Phase 4.1-4.2 (Test infra) - validate as we go
4. Phase 3 (Multi-disk) - after single-disk works
5. Phase 5 (CLI tools) - polish
6. Phase 6 (Docs) - ongoing, finalize at end

* Dependencies

- Phase 2 depends on Phase 1 (refactored code)
- Phase 3 depends on Phase 2 (btrfs basics)
- Phase 4 can run in parallel with 2-3
- Phase 5 depends on Phase 2
- Phase 6 is ongoing

* Open Items

- [ ] File ZFSBootMenu rollback bug
- [ ] Decide: offer archsetup --chroot during install? (TODO exists)