# 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](https://git.cryodev.xyz/steffen/cryodev-server/releases)

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

```bash
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

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

### 3. Write to SD Card

```bash
# 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](new-client.md) 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`:

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

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

## Building Manually

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

```nix
{
  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?