(untested) config for stinky and diff script.

docs/RASPBERRY_PI_SD_IMAGE.md

@@ -0,0 +1,98 @@
+# Raspberry Pi SD Image Building and Deployment
+
+Guide for building and deploying NixOS SD card images for Raspberry Pi hosts (e.g., stinky).
+
+## Overview
+
+Raspberry Pi hosts use a different deployment strategy than regular NixOS hosts:
+- **First deployment**: Build and flash an SD card image
+- **Subsequent updates**: Use `deploy-rs` like other hosts
+
+## Architecture
+
+### Storage Layout
+
+**Partition structure** (automatically created by NixOS):
+- `/boot/firmware` - FAT32 partition (label: `FIRMWARE`)
+  - Contains Raspberry Pi firmware, U-Boot bootloader, device trees
+- `/` - tmpfs (in-memory, ephemeral root)
+  - 2GB RAM disk, wiped on every boot
+- `/nix` - ext4 partition (label: `NIXOS_SD`)
+  - Nix store and persistent data
+  - Contains `/nix/persist` directory for impermanence
+
+### Impermanence with tmpfs
+
+Unlike btrfs-based hosts that use `/persist`, Pi hosts use `/nix/persist`:
+- Root filesystem is tmpfs (no disk writes, auto-wiped)
+- Single ext4 partition mounted at `/nix`
+- Persistent data stored in `/nix/persist/` (directory, not separate mount)
+- Better for SD card longevity (fewer writes)
+
+**Persisted paths**:
+- `/nix/persist/var/lib/nixos` - System state
+- `/nix/persist/home/ppetru` - User home directory
+- `/nix/persist/etc` - SSH host keys, machine-id
+- Service-specific: `/nix/persist/var/lib/octoprint`, etc.
+
+## Building the SD Image
+
+### Prerequisites
+
+- ARM64 emulation enabled on build machine:
+  ```nix
+  boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
+  ```
+  (Already configured in `workstation-node.nix`)
+
+### Build Command
+
+```bash
+# Build SD image for stinky
+nix build .#stinky-sdImage
+
+# Result location
+ls -lh result/sd-image/
+# nixos-sd-image-stinky-25.05-*.img.zst (compressed with zstd)
+```
+
+**Build location**: Defined in `flake.nix`:
+```nix
+packages.aarch64-linux.stinky-sdImage =
+  self.nixosConfigurations.stinky.config.system.build.sdImage;
+```
+
+## Flashing the SD Card
+
+### Find SD Card Device
+
+```bash
+# Before inserting SD card
+lsblk
+
+# Insert SD card, then check again
+lsblk
+
+# Look for new device, typically:
+# - /dev/sdX (USB SD card readers)
+# - /dev/mmcblk0 (built-in SD card slots)
+```
+
+**Warning**: Double-check the device! Wrong device = data loss.
+
+### Flash Image
+
+```bash
+# Decompress and flash in one command
+zstd -d -c result/sd-image/*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
+
+# Or decompress first, then flash
+unzstd result/sd-image/*.img.zst
+sudo dd if=result/sd-image/*.img of=/dev/sdX bs=4M status=progress conv=fsync
+```
+
+### Eject SD Card
+
+```bash
+sudo eject /dev/sdX
+```