Add SD image pipeline, documentation overhaul, and fix module issues

- Add automatic SD image builds for Raspberry Pi via Forgejo Actions - Enable binfmt emulation on cryodev-main for aarch64 cross-builds - Add sd-image.nix module to cryodev-pi configuration - Create comprehensive docs/ structure with installation guides - Split installation docs into: first-install (server), reinstall, new-client (Pi) - Add lib/utils.nix and apps/rebuild from synix - Fix headplane module for new upstream API (tale/headplane) - Fix various module issues (mailserver stateVersion, option conflicts) - Add placeholder secrets.yaml files for both hosts - Remove old INSTRUCTIONS.md (content moved to docs/)
2026-03-11 08:41:58 +01:00 · 2026-03-11 08:41:58 +01:00 · 5ba78886d2
commit 5ba78886d2
parent a5261d8ff0
44 changed files with 3570 additions and 609 deletions
--- a/docs/deployment/cd.md
+++ b/docs/deployment/cd.md
@ -0,0 +1,174 @@
+# Continuous Deployment
+
+The cryodev infrastructure uses two deployment strategies optimized for different host types.
+
+## Overview
+
+| Host | Strategy | Tool | Trigger |
+|------|----------|------|---------|
+| `cryodev-main` | Push-based | deploy-rs | Git push via Forgejo Actions |
+| `cryodev-pi` | Pull-based | Comin | Periodic polling |
+
+## Push-based Deployment (cryodev-main)
+
+### How It Works
+
+1. Developer pushes to `main` branch
+2. Forgejo Actions workflow triggers
+3. `deploy-rs` connects via SSH and deploys
+
+### Setup
+
+#### 1. Generate Deploy Key
+
+```bash
+ssh-keygen -t ed25519 -f deploy_key -C "forgejo-actions"
+```
+
+#### 2. Add Public Key to Server
+
+On `cryodev-main`:
+
+```bash
+echo "PUBLIC_KEY_CONTENT" >> /root/.ssh/authorized_keys
+```
+
+#### 3. Add Private Key to Forgejo
+
+1. Go to Repository Settings > Secrets
+2. Add secret named `DEPLOY_SSH_KEY`
+3. Paste the private key content
+
+#### 4. Workflow Configuration
+
+`.forgejo/workflows/deploy.yaml`:
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v24
+      - run: nix flake check
+
+  deploy:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v24
+      
+      - name: Setup SSH
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan cryodev-main >> ~/.ssh/known_hosts
+          
+      - name: Deploy
+        run: nix run github:serokell/deploy-rs -- .#cryodev-main
+```
+
+### Rollback
+
+deploy-rs automatically rolls back if the new configuration fails health checks.
+
+Manual rollback:
+
+```bash
+# List generations
+sudo nix-env -p /nix/var/nix/profiles/system --list-generations
+
+# Rollback to previous
+sudo nixos-rebuild switch --rollback
+```
+
+## Pull-based Deployment (cryodev-pi)
+
+### How It Works
+
+1. Comin periodically polls the Git repository
+2. On changes, it builds and activates the new configuration
+3. Works through NAT without incoming connections
+
+### Configuration
+
+```nix
+# hosts/cryodev-pi/services/comin.nix
+{
+  services.comin = {
+    enable = true;
+    remotes = [{
+      name = "origin";
+      url = "https://git.cryodev.xyz/steffen/cryodev-server.git";
+      branches.main.name = "main";
+    }];
+  };
+}
+```
+
+### Monitoring
+
+Check Comin status:
+
+```bash
+sudo systemctl status comin
+sudo journalctl -u comin -f
+```
+
+Force immediate update:
+
+```bash
+sudo systemctl restart comin
+```
+
+### Troubleshooting
+
+If Comin fails to build:
+
+```bash
+# Check logs
+sudo journalctl -u comin --since "1 hour ago"
+
+# Manual build test
+cd /var/lib/comin/repo
+nix build .#nixosConfigurations.cryodev-pi.config.system.build.toplevel
+```
+
+## Manual Deployment
+
+For hosts not using automated deployment:
+
+```bash
+# Build locally
+nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
+
+# Deploy with nixos-rebuild
+nixos-rebuild switch --flake .#<hostname> --target-host root@<hostname>
+
+# Or using deploy-rs
+nix run github:serokell/deploy-rs -- .#<hostname>
+```
+
+## Testing Changes
+
+Before pushing, always verify:
+
+```bash
+# Check flake validity
+nix flake check
+
+# Build configuration (dry-run)
+nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel --dry-run
+
+# Full build
+nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
+```