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:
```
boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
```
(Already configured in workstation-node.nix)

Build Command

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

packages.aarch64-linux.stinky-sdImage =
  self.nixosConfigurations.stinky.config.system.build.sdImage;

Flashing the SD Card

Find SD Card Device

# 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

# 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

sudo eject /dev/sdX

2.5 KiB Raw Blame History