cryodev/docs/getting-started/sd-image.md

SD Card Images for Raspberry Pi

The repository automatically builds SD card images for all configured Raspberry Pi hosts.

Automatic Build

When changes are pushed to main, images are automatically built for all Pi hosts and published as a release.

Download: Releases on Forgejo

Available Images

Host	Image Name
cryodev-pi	cryodev-pi-sd-image.img.zst

New hosts are built automatically once they are added to the workflow matrix.

Flashing the Image

1. Download

wget https://git.cryodev.xyz/.../releases/latest/download/<hostname>-sd-image.img.zst
wget https://git.cryodev.xyz/.../releases/latest/download/<hostname>-sd-image.img.zst.sha256

# Verify checksum
sha256sum -c <hostname>-sd-image.img.zst.sha256

2. Decompress

zstd -d <hostname>-sd-image.img.zst -o <hostname>.img

3. Write to SD Card

# Identify the correct device
lsblk

# Write (WARNING: make sure to select the correct device!)
sudo dd if=<hostname>.img of=/dev/sdX bs=4M conv=fsync status=progress

Alternatively, use balenaEtcher or Raspberry Pi Imager.

What Is Included in the Image?

• Complete NixOS installation for the specific host
• All configured services (except secrets)
• SSH server enabled
• Automatic root partition expansion on first boot
• Comin for automatic updates

What Is Missing?

SOPS secrets cannot be included in the image (chicken-and-egg problem with the SSH host key).

After the first boot:

1. Retrieve the age key from the Pi
2. Update .sops.yaml
3. Create secrets.yaml
4. Deploy the configuration

See Adding a New Client for the complete guide.

Adding a New Host to the Pipeline

1. Create the host configuration in hosts/<hostname>/
2. Add it to the matrix in .forgejo/workflows/build-pi-image.yml:

matrix:
  host: [cryodev-pi, new-host]  # <- add here

3. Push to main -- the image will be built automatically

Building Manually

# On aarch64 (e.g., another Pi)
nix build .#nixosConfigurations.<hostname>.config.system.build.sdImage

# On x86_64 with QEMU emulation (slow)
nix build .#nixosConfigurations.<hostname>.config.system.build.sdImage \
  --extra-platforms aarch64-linux

Prerequisite on x86_64:

{
  boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
}

Troubleshooting

Workflow Fails

• Check whether sd-image.nix is imported in the host configuration
• Check whether binfmt is enabled on cryodev-main

Image Does Not Boot

• Was the SD card written correctly?
• Try a different SD card
• Check the power supply (minimum 3A for Pi 4)

No Network

• Check the Ethernet cable
• Is there a DHCP server on the network?