cryodev/README.md

cryodev-server 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.

---

🇬🇧 English Description

Overview

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.

Key Features & Architecture

🖥️ Hosts

• cryodev-main (x86_64 Server): The core infrastructure hub.
• cryodev-pi (Raspberry Pi 4): A remote client/worker node.

🚀 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. This ensures immediate updates and robust rollbacks in case of failure.
• Pull-based (Client): The Raspberry Pi uses Comin to periodically poll the Git repository and apply updates automatically. This is ideal for devices behind NAT or with unstable connections.

🌐 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.

📊 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.

📧 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.

🛠️ 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 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.

🚧 Roadmap & Missing Features

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.

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.

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.

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.

---

🇩🇪 Deutsche Beschreibung

Überblick

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.

Hauptfunktionen & Architektur

🖥️ Hosts

• cryodev-main (x86_64 Server): Der zentrale Infrastruktur-Knoten.
• cryodev-pi (Raspberry Pi 4): Ein entfernter Client/Worker-Node.

🚀 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 aktualisiert. Dies garantiert sofortige Updates und robuste Rollbacks bei Fehlern.
• Pull-basiert (Client): Der Raspberry Pi nutzt Comin, um das Git-Repository periodisch abzufragen und Updates automatisch anzuwenden. Ideal für Geräte hinter NAT oder mit instabilen Verbindungen.

🌐 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.

📊 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 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.