steffen/cryodev
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

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

Browse source 
- 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/)
This commit is contained in:
steffen 2026-03-11 08:41:58 +01:00
parent a5261d8ff0
commit 5ba78886d2
44 changed files with 3570 additions and 609 deletions
Download patch file Download diff file Expand all files Collapse all files

193
README.md
View file

@ -1,147 +1,100 @@
# cryodev-server NixOS Configuration
# cryodev NixOS Configuration
This repository contains the declarative NixOS configuration for the **cryodev** infrastructure, managed using **Nix Flakes**. It defines a robust, secure, and self-hosted environment spanning a main server and client devices.
Declarative NixOS infrastructure for the **cryodev** environment, managed with Nix Flakes.
---
## Quick Start
# 🇬🇧 English Description
```bash
# Clone repository
git clone https://git.cryodev.xyz/steffen/cryodev-server.git
cd cryodev-server
## Overview
# Check configuration
nix flake check
The infrastructure is designed around a central server (`cryodev-main`) and satellite clients (e.g., `cryodev-pi`). It leverages modern DevOps practices including Infrastructure as Code (IaC), GitOps, and Mesh VPNs.
# Build a host
nix build .#nixosConfigurations.cryodev-main.config.system.build.toplevel
```
## Key Features & Architecture
## Hosts
### 🖥️ Hosts
* **`cryodev-main` (x86_64 Server)**: The core infrastructure hub.
* **`cryodev-pi` (Raspberry Pi 4)**: A remote client/worker node.
| Host | Architecture | Deployment | Description |
|------|--------------|------------|-------------|
| `cryodev-main` | x86_64 | Push (deploy-rs) | Main server |
| `cryodev-pi` | aarch64 | Pull (Comin) | Raspberry Pi client |
### 🚀 Continuous Deployment (CD)
We utilize different deployment strategies optimized for each host type:
* **Push-based (Server):** The main server is deployed via **Forgejo Actions** using **[deploy-rs](https://github.com/serokell/deploy-rs)**. This ensures immediate updates and robust rollbacks in case of failure.
* **Pull-based (Client):** The Raspberry Pi uses **[Comin](https://github.com/nlewo/comin)** to periodically poll the Git repository and apply updates automatically. This is ideal for devices behind NAT or with unstable connections.
## Services
### 🌐 Networking (Tailscale & Headscale)
* **Self-hosted VPN:** We run **Headscale**, an open-source implementation of the Tailscale control server.
* **Headplane:** A web frontend for managing Headscale users and routes.
* **Mesh Network:** All hosts are connected via a secure, private WireGuard mesh network.
* **MagicDNS:** Automatic DNS resolution for devices within the tailnet.
| Service | Domain | Description |
|---------|--------|-------------|
| Headscale | `headscale.cryodev.xyz` | Self-hosted Tailscale server |
| Headplane | `headplane.cryodev.xyz` | Headscale web UI |
| Forgejo | `git.cryodev.xyz` | Git hosting with CI/CD |
| Netdata | `netdata.cryodev.xyz` | Monitoring dashboard |
| Mail | `mail.cryodev.xyz` | Email (Postfix/Dovecot) |
### 📊 Monitoring (Netdata)
* **Parent/Child Streaming:** The main server acts as a centralized Netdata parent node.
* **Distributed Monitoring:** `cryodev-pi` (and other clients) stream their metrics securely over the Tailscale VPN to the parent node.
* **Alerting:** Integrated with the mailserver to send health alerts.
## Raspberry Pi SD Images
### 📧 Mail Services
* **NixOS Mailserver:** A fully functional mail stack (Postfix/Dovecot).
* **Integration:** Used by internal services (Forgejo, Netdata) to send notifications.
* **Security:** SPF, DKIM, and DMARC configured for `cryodev.xyz`.
SD card images for Raspberry Pi clients are **built automatically** on every push to `main`.
### 🛠️ Development & Productivity
* **Forgejo:** Self-hosted Git service (fork of Gitea) with built-in CI/CD Actions.
* **Forgejo Runner:** Self-hosted runners executing the CI/CD pipelines.
* **Neovim:** A fully pre-configured Neovim environment (aliased as `v`) available system-wide via a custom NixOS module.
* **Secret Management:** **[sops-nix](https://github.com/Mic92/sops-nix)** encrypts secrets using Age and SSH host keys, ensuring no sensitive data is committed in plain text.
* **Templates:** Ready-to-use NixOS configurations for quickly bootstrapping new clients.
* `#raspberry-pi`: Template for Raspberry Pi 4 clients.
* `#generic-server`: Template for generic x86_64 servers.
* **Bootstrap Script:** An `install.sh` script automates disk partitioning (via disko) and system installation for new hosts.
Download from: [Releases](https://git.cryodev.xyz/steffen/cryodev-server/releases)
## 🚧 Roadmap & Missing Features
```bash
# Flash to SD card
zstd -d cryodev-pi-sd-image.img.zst
sudo dd if=cryodev-pi-sd-image.img of=/dev/sdX bs=4M status=progress
```
### BioSafe Gateway (Dual Ethernet)
The Raspberry Pi hosts utilize a custom board with two Ethernet ports:
* **WAN:** Standard Internet connection.
* **LAN (`eth1`):** A dedicated local connection managed specifically by the **BioSafe Gateway App**.
* *Status:* The network configuration logic and the integration of the controlling app are currently missing.
See [Adding a new Raspberry Pi](docs/getting-started/new-client.md) for the full workflow.
### Closed Source Integration
The **BioSafe Gateway App** is closed source.
* It needs to be added as a **private Flake input**.
* Authentication mechanism (e.g., access tokens via Secrets) to fetch this private input during the build process is not yet implemented.
## Documentation
### SD Card Image Pipeline
Currently, the Pi requires manual setup.
* *Goal:* A CI/CD pipeline that builds a fully configured, flashable SD card image.
* *Usage:* Download image -> Flash to SD -> Insert in Pi -> Boot & Auto-connect.
Full documentation is available in the [`docs/`](docs/index.md) directory:
- [Prerequisites](docs/getting-started/prerequisites.md)
- [New Raspberry Pi Client](docs/getting-started/new-client.md)
- [SD Image Reference](docs/getting-started/sd-image.md)
- [Server Installation](docs/getting-started/first-install.md)
- [Reinstallation](docs/getting-started/reinstall.md)
- [Services](docs/services/)
- [Deployment](docs/deployment/cd.md)
## Directory Structure
* `flake.nix`: The entry point defining inputs (dependencies) and outputs (system configs).
* `hosts/`: Configuration specific to each machine.
* `modules/`: Reusable NixOS modules (custom or imported).
* `pkgs/`: Custom packages.
* `constants.nix`: Central source of truth for IPs, ports, and domains.
* `INSTRUCTIONS.md`: Detailed setup guide (DNS, SOPS, Initial Deployment).
* `AGENTS.md`: Guidelines for AI agents working on this repository.
---
```
.
├── flake.nix # Flake entry point
├── constants.nix # Central configuration
├── hosts/ # Host configurations
├── modules/ # Reusable NixOS modules
├── pkgs/ # Custom packages
├── overlays/ # Nixpkgs overlays
├── templates/ # Host templates
├── scripts/ # Helper scripts
├── apps/ # Nix apps (rebuild)
├── lib/ # Helper functions
└── docs/ # Documentation
```
# 🇩🇪 Deutsche Beschreibung
## Commands
## Überblick
```bash
# Format code
nix fmt
Die Infrastruktur ist um einen zentralen Server (`cryodev-main`) und Satelliten-Clients (z.B. `cryodev-pi`) herum aufgebaut. Sie nutzt moderne DevOps-Praktiken wie Infrastructure as Code (IaC), GitOps und Mesh-VPNs.
# Run checks
nix flake check
## Hauptfunktionen & Architektur
# Update dependencies
nix flake update
### 🖥️ Hosts
* **`cryodev-main` (x86_64 Server)**: Der zentrale Infrastruktur-Knoten.
* **`cryodev-pi` (Raspberry Pi 4)**: Ein entfernter Client/Worker-Node.
# Enter dev shell
nix develop
### 🚀 Continuous Deployment (CD)
Wir verwenden unterschiedliche Deployment-Strategien, optimiert für den jeweiligen Host-Typ:
* **Push-basiert (Server):** Der Hauptserver wird über **Forgejo Actions** mittels **[deploy-rs](https://github.com/serokell/deploy-rs)** aktualisiert. Dies garantiert sofortige Updates und robuste Rollbacks bei Fehlern.
* **Pull-basiert (Client):** Der Raspberry Pi nutzt **[Comin](https://github.com/nlewo/comin)**, um das Git-Repository periodisch abzufragen und Updates automatisch anzuwenden. Ideal für Geräte hinter NAT oder mit instabilen Verbindungen.
# Build Pi SD image locally
nix build .#nixosConfigurations.cryodev-pi.config.system.build.sdImage
```
### 🌐 Netzwerk (Tailscale & Headscale)
* **Self-hosted VPN:** Wir betreiben **Headscale**, eine Open-Source-Implementierung des Tailscale-Kontrollservers.
* **Headplane:** Ein Web-Frontend zur Verwaltung von Headscale-Benutzern und Routen.
* **Mesh-Netzwerk:** Alle Hosts sind über ein sicheres, privates WireGuard-Mesh-Netzwerk verbunden.
* **MagicDNS:** Automatische Namensauflösung für Geräte innerhalb des Tailnets.
## License
### 📊 Monitoring (Netdata)
* **Parent/Child Streaming:** Der Hauptserver agiert als zentraler Netdata Parent-Node.
* **Verteiltes Monitoring:** `cryodev-pi` (und andere Clients) streamen ihre Metriken sicher über das Tailscale-VPN an den Parent-Node.
* **Alarmierung:** Integriert mit dem Mailserver zum Versenden von Gesundheitswarnungen.
### 📧 Mail-Dienste
* **NixOS Mailserver:** Ein voll funktionsfähiger Mail-Stack (Postfix/Dovecot).
* **Integration:** Wird von internen Diensten (Forgejo, Netdata) für Benachrichtigungen genutzt.
* **Sicherheit:** SPF, DKIM und DMARC sind für `cryodev.xyz` konfiguriert.
### 🛠️ Entwicklung & Produktivität
* **Forgejo:** Self-hosted Git-Dienst (Gitea-Fork) mit integrierten CI/CD Actions.
* **Forgejo Runner:** Eigene Runner, die die CI/CD-Pipelines ausführen.
* **Neovim:** Eine vollständig vorkonfigurierte Neovim-Umgebung (Alias `v`), die systemweit über ein eigenes NixOS-Modul bereitgestellt wird.
* **Secret Management:** **[sops-nix](https://github.com/Mic92/sops-nix)** verschlüsselt Geheimnisse mittels Age und SSH-Host-Keys, sodass keine sensiblen Daten im Klartext gespeichert werden.
* **Templates:** Vorgefertigte NixOS-Konfigurationen zum schnellen Aufsetzen neuer Clients.
* `#raspberry-pi`: Template für Raspberry Pi 4 Clients.
* `#generic-server`: Template für generische x86_64 Server.
* **Bootstrap Skript:** Ein `install.sh` Skript automatisiert die Disk-Partitionierung (via disko) und Systeminstallation für neue Hosts.
## 🚧 Roadmap & Fehlende Funktionen
### BioSafe Gateway (Dual-Ethernet)
Die Raspberry Pi Hosts nutzen ein spezielles Board mit zwei Ethernet-Anschlüssen:
* **WAN:** Normale Internetverbindung.
* **LAN (`eth1`):** Eine dedizierte lokale Verbindung, die spezifisch durch die **BioSafe Gateway App** verwaltet wird.
* *Status:* Die Logik für die Netzwerkkonfiguration und die Integration der steuernden App fehlen aktuell.
### Integration von Closed Source
Die **BioSafe Gateway App** ist Closed Source.
* Sie muss als **privater Flake Input** hinzugefügt werden.
* Mechanismen zur Authentifizierung (z.B. Access Tokens via Secrets) für das Abrufen dieses privaten Inputs während des Build-Prozesses sind noch nicht implementiert.
### Pipeline für SD-Karten-Images
Momentan erfordert der Pi eine manuelle Einrichtung.
* *Ziel:* Eine CI/CD-Pipeline, die ein fertig konfiguriertes, flashbares SD-Karten-Image baut.
* *Nutzung:* Image herunterladen -> auf SD flashen -> in Pi stecken -> booten & automatisch verbinden.
## Verzeichnisstruktur
* `flake.nix`: Der Einstiegspunkt, der Inputs (Abhängigkeiten) und Outputs (Systemkonfigurationen) definiert.
* `hosts/`: Maschinenspezifische Konfigurationen.
* `modules/`: Wiederverwendbare NixOS-Module (eigene oder importierte).
* `pkgs/`: Benutzerdefinierte Pakete.
* `constants.nix`: Zentrale Quelle für IPs, Ports und Domains.
* `INSTRUCTIONS.md`: Detaillierte Einrichtungsanleitung (DNS, SOPS, Initial Deployment).
* `AGENTS.md`: Richtlinien für KI-Agenten, die an diesem Repository arbeiten.
Private repository.