a0da5be8fc
Translate 8 documentation files from German to English: - docs/index.md (complete) - docs/getting-started/first-install.md (complete) - docs/getting-started/new-client.md (complete) - docs/getting-started/reinstall.md (complete) - docs/getting-started/sd-image.md (complete) - docs/deployment/dns.md (PTR, Hetzner, checklist sections) - docs/services/tailscale.md (code comments) - docs/services/forgejo.md (placeholder names)
116 lines
2.7 KiB
Markdown
116 lines
2.7 KiB
Markdown
# 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?
|