147 lines
8.9 KiB
Markdown
147 lines
8.9 KiB
Markdown
# 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](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.
|
|
|
|
### 🌐 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](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.
|
|
|
|
## 🚧 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](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.
|
|
|
|
### 🌐 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](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.
|