# NixBook ext4 to btrfs Migration Guide

## Overview
This guide converts your nixbook machine from ext4 to btrfs with zstd compression and beesd deduplication while preserving your LUKS encryption and all data.

## Current System Info
- **Hostname**: nix-book
- **Root filesystem**: ext4 on `/dev/disk/by-uuid/bd396529-e2c4-47cb-b844-8d6ed841f81a`
- **Encryption**: LUKS with two devices configured
- **Current usage**: 138GB used / 225GB total (65% full)
- **Free space**: 76GB available (sufficient for conversion)

## Pre-Migration Checklist

### 1. Create Full System Backup (CRITICAL)
```bash
# Boot from NixOS live USB
# Mount encrypted filesystem
cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
mount /dev/mapper/luks-nixbook /mnt

# Create backup to external drive (adjust target as needed)
rsync -avxHAX --progress /mnt/ /path/to/backup/nixbook-backup/
```

### 2. Verify Configuration Changes
The following files have been updated for btrfs:
- `machines/nix-book/configuration.nix` - Added beesd service
- `machines/nix-book/hardware-configuration.nix` - Changed fsType to btrfs with compression

## Migration Process

### Phase 1: Boot to Live Environment
1. **Create NixOS live USB**:
   ```bash
   # Download latest NixOS ISO
   # Flash to USB drive
   dd if=nixos-minimal-xx.xx-x86_64-linux.iso of=/dev/sdX bs=4M status=progress
   ```

2. **Boot from live USB** and ensure you can access the encrypted drives

### Phase 2: Filesystem Conversion
3. **Unlock LUKS volumes**:
   ```bash
   cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
   cryptsetup luksOpen /dev/disk/by-uuid/b614167b-9045-4234-a441-ac6f60a96d81 luks-nixbook2
   ```

4. **Check filesystem before conversion**:
   ```bash
   fsck.ext4 -f /dev/mapper/luks-nixbook
   ```

5. **Convert ext4 to btrfs** (this preserves all data):
   ```bash
   # Install btrfs-progs if not available
   nix-shell -p btrfs-progs

   # Convert the filesystem (takes 15-45 minutes depending on data)
   btrfs-convert /dev/mapper/luks-nixbook
   
   # Verify conversion succeeded
   mount /dev/mapper/luks-nixbook /mnt
   ls -la /mnt  # Should show your normal filesystem
   btrfs filesystem show /mnt
   ```

6. **Get new filesystem UUID** (may have changed):
   ```bash
   blkid /dev/mapper/luks-nixbook
   # Note the new UUID if it changed
   ```

### Phase 3: Configuration Update
7. **Mount and chroot into system**:
   ```bash
   mount -o compress=zstd,noatime /dev/mapper/luks-nixbook /mnt
   mount /dev/disk/by-uuid/7A0B-CF88 /mnt/boot
   nixos-enter --root /mnt
   ```

8. **Update hardware-configuration.nix** if UUID changed:
   ```bash
   # Edit /etc/nixos/hardware-configuration.nix if needed
   # Update the UUID in fileSystems."/" section
   ```

9. **Rebuild system with btrfs configuration**:
   ```bash
   cd /home/johno/nixos-configs
   nixos-rebuild switch --flake .#nix-book
   ```

### Phase 4: Enable Compression and Deduplication
10. **Reboot into new btrfs system**:
    ```bash
    exit  # Exit chroot
    umount -R /mnt
    reboot
    ```

11. **Verify btrfs is working**:
    ```bash
    mount | grep btrfs
    btrfs filesystem usage /
    ```

12. **Enable and start beesd**:
    ```bash
    systemctl status beesd-root
    systemctl start beesd-root
    systemctl enable beesd-root
    ```

13. **Force compression on existing files** (optional but recommended):
    ```bash
    # This will compress existing files with zstd
    btrfs filesystem defragment -r -czstd /
    ```

## Post-Migration Verification

### Check System Health
```bash
# Verify btrfs health
btrfs scrub start /
btrfs scrub status /

# Check compression effectiveness
compsize /

# Monitor beesd deduplication
journalctl -u beesd-root -f

# Check filesystem usage
btrfs filesystem usage /
df -h /
```

### Performance Monitoring
```bash
# Monitor beesd hash table
ls -lh /.beeshash

# Check compression ratio over time
compsize /home /nix /var
```

## Expected Benefits

### Space Savings
- **Compression**: 20-30% reduction in disk usage from zstd
- **Deduplication**: Additional 10-20% savings on duplicate files
- **Combined**: Potentially 30-40% total space savings

### Performance Impact
- **Compression**: Minimal CPU overhead, often improves I/O performance
- **Deduplication**: Background process, minimal impact during normal use
- **Overall**: Should be neutral to positive performance impact

## Rollback Plan (Emergency)

If something goes wrong:

1. **Boot from live USB**
2. **Restore from backup**:
   ```bash
   cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
   mkfs.ext4 /dev/mapper/luks-nixbook
   mount /dev/mapper/luks-nixbook /mnt
   rsync -avxHAX --progress /path/to/backup/nixbook-backup/ /mnt/
   ```
3. **Restore original hardware-configuration.nix** with ext4 settings
4. **Rebuild and reboot**

## Troubleshooting

### Common Issues

**"Device busy" during conversion**:
- Ensure no processes are accessing the filesystem
- Check with `lsof` and `fuser`

**UUID changed after conversion**:
- Update hardware-configuration.nix with new UUID
- Regenerate initrd: `nixos-rebuild switch`

**Beesd service fails to start**:
- Check disk space for hash table
- Verify filesystem is btrfs: `mount | grep btrfs`
- Check logs: `journalctl -u beesd-root`

**Boot issues after conversion**:
- Boot from live USB
- Check /boot partition is mounted correctly
- Verify LUKS UUIDs match in configuration
- Rebuild bootloader: `nixos-rebuild switch --install-bootloader`

## Maintenance

### Regular Tasks
```bash
# Monthly scrub (checks for corruption)
btrfs scrub start /

# Monitor compression effectiveness
compsize /

# Check beesd deduplication status
systemctl status beesd-root
```

### Space Management
```bash
# Balance filesystem (defragments and optimizes)
btrfs balance start -dusage=50 /

# Check for space issues
btrfs filesystem usage /
```

This migration preserves all your data while gaining the benefits of modern btrfs features including transparent compression and automatic deduplication.