cryodev/docs/getting-started/new-client.md

# Adding a New Raspberry Pi Client

This guide describes how to add a **new Raspberry Pi client** to the infrastructure.

## Overview: The Process

```
1. Create configuration         ──► Copy template, customize
         │
         ▼
2. Add to image pipeline        ──► Extend workflow matrix
         │
         ▼
3. Push to main                 ──► Forgejo automatically builds SD image
         │
         ▼
4. Flash image & boot           ──► Write SD card, start Pi
         │
         ▼
5. Configure SOPS               ──► Retrieve age key, create secrets
         │
         ▼
6. Final deployment             ──► Activate Tailscale etc.
```

## Prerequisites

- SSH access to cryodev-main (for Tailscale auth key)
- Development machine with repository access
- SD card (at least 8 GB)

---

## Step 1: Generate Tailscale Auth Key

**On cryodev-main** (via SSH):

```bash
# Determine user ID
sudo headscale users list
# Create preauth key (use user ID of "default")
sudo headscale preauthkeys create --expiration 99y --reusable --user <ID>
```

**Take note of the output!** (e.g. `tskey-preauth-abc123...`)

---

## Step 2: Create Host Configuration

### 2.1 Copy Template

```bash
cp -r templates/raspberry-pi hosts/neuer-pi
```

### 2.2 Set Hostname

`hosts/neuer-pi/networking.nix`:

```nix
{
  networking.hostName = "neuer-pi";
}
```

### 2.3 Register in flake.nix

```nix
nixosConfigurations = {
  # ... existing hosts ...
  
  neuer-pi = mkNixosConfiguration "aarch64-linux" [ ./hosts/neuer-pi ];
};
```

### 2.4 Add to constants.nix

```nix
{
  hosts = {
    # ... existing hosts ...
    
    neuer-pi = {
      ip = "100.64.0.X";  # Assigned by Headscale
    };
  };
}
```

### 2.5 Create Placeholder secrets.yaml

```bash
touch hosts/neuer-pi/secrets.yaml
```

### 2.6 Temporarily Disable SOPS

In `hosts/neuer-pi/default.nix`, comment out the `sops.secrets.*` references so the image can be built without secrets.

---

## Step 3: Add to Image Pipeline

Edit `.forgejo/workflows/build-pi-image.yml`:

```yaml
jobs:
  build-pi-images:
    strategy:
      matrix:
        # Add new host here:
        host: [cryodev-pi, neuer-pi]
```

---

## Step 4: Push and Build Image

```bash
git add .
git commit -m "Add neuer-pi host configuration"
git push
```

The Forgejo workflow will now automatically build an SD image for `neuer-pi`.

**Wait** until the workflow completes (30-60 minutes). Check the status at:
`https://git.cryodev.xyz/steffen/cryodev-server/actions`

---

## Step 5: Flash Image

### 5.1 Download Image

After a successful build, find the image under **Releases**:

```bash
wget https://git.cryodev.xyz/steffen/cryodev-server/releases/latest/download/neuer-pi-sd-image.img.zst
```

### 5.2 Decompress

```bash
zstd -d neuer-pi-sd-image.img.zst -o neuer-pi.img
```

### 5.3 Write to SD Card

**Warning:** Replace `/dev/sdX` with the correct device!

```bash
lsblk  # Identify the correct device
sudo dd if=neuer-pi.img of=/dev/sdX bs=4M conv=fsync status=progress
```

### 5.4 Boot

1. Insert the SD card into the Raspberry Pi
2. Connect Ethernet
3. Connect power
4. Wait until booted (approximately 2 minutes)

---

## Step 6: Configure SOPS

### 6.1 Find IP Address

The Pi should receive an IP address via DHCP. Check your router or scan the network:

```bash
nmap -sn 192.168.1.0/24 | grep -B2 "Raspberry"
```

### 6.2 Connect via SSH

```bash
ssh steffen@<IP>  # or the configured user
```

For the default password, see `hosts/neuer-pi/users.nix`.

### 6.3 Determine Age Key

On the Pi:

```bash
nix-shell -p ssh-to-age --run 'cat /etc/ssh/ssh_host_ed25519_key.pub | ssh-to-age'
```

**Take note of the output!** (e.g. `age1xyz...`)

### 6.4 Update .sops.yaml

On the development machine:

```yaml
keys:
  - &steffen_key age1e8p35795htf7twrejyugpzw0qja2v33awcw76y4gp6acnxnkzq0s935t4t  # steffen (local)
  - &neuer_pi_key age1xyz...  # The new key

creation_rules:
  # ... existing rules ...

  - path_regex: hosts/neuer-pi/secrets.yaml$
    key_groups:
      - age:
          - *steffen_key
          - *neuer_pi_key
```

### 6.5 Create Secrets

```bash
sops hosts/neuer-pi/secrets.yaml
```

Contents:

```yaml
tailscale:
  auth-key: "tskey-preauth-abc123..."  # Key from Step 1

netdata:
  stream:
    child-uuid: "..."  # uuidgen
```

### 6.6 Activate SOPS References

Re-enable the `sops.secrets.*` references that were commented out in Step 2.6.

---

## Step 7: Final Deployment

```bash
git add .
git commit -m "Configure SOPS secrets for neuer-pi"
git push
```

Since Comin is running on the Pi, it will automatically pull the new configuration.

Alternatively, deploy manually:

```bash
NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#neuer-pi \
  --target-host <user>@<IP> --sudo --ask-sudo-password
```

---

## Step 8: Verify

### Tailscale Connection

```bash
# On the Pi
tailscale status

# On cryodev-main
sudo headscale nodes list
```

### Netdata Streaming

Check whether the new client appears in the Netdata dashboard:
`https://netdata.cryodev.xyz`

---

## Checklist

- [ ] Tailscale auth key generated on cryodev-main
- [ ] Host configuration created (template, flake.nix, constants.nix)
- [ ] Host added to workflow matrix
- [ ] Pushed and waited for image build
- [ ] SD card flashed and Pi booted
- [ ] Age key determined and added to .sops.yaml
- [ ] secrets.yaml created (Tailscale key, Netdata UUID)
- [ ] SOPS references activated and deployed
- [ ] Tailscale connection working
- [ ] Netdata streaming working