99 lines
2.5 KiB
Markdown
99 lines
2.5 KiB
Markdown
# 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 .#packages.aarch64-linux.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
|
|
```
|