---
type: Guide
status: ACTIVE
owner: DevOps Engineer
---
# Technisches Referenzhandbuch: MS-R1 "Das Biest"

## 1. System-Übersicht & Architektur

Das System "MS-R1" (interner Codename "Zora") ist ein High-End ARM64-Server auf Basis des CIX P1 SoC. 

### Hardware-Spezifikationen

* **CPU:** ARM64 Architektur (CIX P1).
* **RAM:** 64 GB LPDDR.
* **Speicher:** NVMe-basiertes Root-Dateisystem.
* **OS:** Debian 12 (Bookworm).

## 2. Design-Entscheidungen & Ausschlussverfahren

### 2.1 Wahl des Betriebssystems

**Entscheidung:** Debian 12 (Bookworm).
**Begründung:** Maximale Stabilität für Infrastruktur-Dienste. 
**Ausschluss:** Ubuntu wurde aufgrund der Snap-Abhängigkeiten und Fedora aufgrund der kürzeren Release-Zyklen ausgeschlossen.

### 2.2 Kernel- & Firewall-Management

**Problem:** Der spezifische ARM-Kernel unterstützt bestimmte moderne `nftables`- und `iptables`-Module (wie `xt_CHECKSUM`) nicht.
**Lösung:** Umstellung auf `iptables-legacy`.
**Vorteil:** Ermöglicht die korrekte Paketverarbeitung für virtuelle Netzwerke, die sonst zu "Hängern" in der UI führen würden.

## 3. Benutzer- und Sicherheitskonzept

Um das System abzusichern, wurde eine strikte Bereinigung der Standard-User durchgeführt.

* **Administrative Accounts:** `grandmo` (Haupt-Admin) und `mastermo` (Redundanz).
* **System-Accounts:** `git` (UID 101) für Anwendungsdienste ohne Sudo-Privilegien.

## Benutzer-Management
Das System verfügt über eine strikte Trennung zwischen Administration und Diensten:

* **grandmo:** Haupt-Administrator (Sudo-Rechte)
* **mastermo:** Backup-Administrator (Sudo-Rechte)
* **git:** System-User für Gitea-Dienste (keine Sudo-Rechte)

## 4. Kritische Wartungsbefehle

Da Incus die Firewall-Regeln aufgrund von Kernel-Einschränkungen nicht selbst injizieren kann (`firewall=false`), muss das NAT-Routing manuell persistiert werden:

```bash
# Manuelles Aktivieren des Internet-Gateways für Container
sudo iptables -t nat -A POSTROUTING -s 10.0.6.0/24 ! -d 10.0.6.0/24 -j MASQUERADE
```

## Kernel- & Firewall-Besonderheiten

Aufgrund der ARM64-Architektur und Kernel-Einschränkungen wurden folgende Anpassungen vorgenommen:

* **Hypervisor:** Proxmox VE 8.4.10 läuft auf Zora (`pve.mo-code.at`, IP `10.0.0.20`).
* **Netz-Bridge:** `vmbr0`, Subnetz `10.0.0.0/24`, Gateway `10.0.0.138`.
* **Firewall-Modus:** Proxmox verwaltet Firewall und NAT automatisch via `vmbr0` — keine manuelle iptables-Regel nötig.

> ℹ️ Frühere Einträge zu Incus/iptables-MASQUERADE sind historisch (Testbetrieb Feb 2026) und wurden durch Proxmox abgelöst.
  
## Wichtige Befehle

* **Neustart erzwingen:** `sudo systemctl reboot`
* **Admin-Rechte prüfen:** `sudo whoami` (sollte 'root' ergeben)

---

## 2. Incus_Konfiguration&Bedienungsanleitung.md

> ⚠️ **HISTORISCH (Testbetrieb Feb 2026) — ABGELÖST durch Proxmox VE 8.4.10**
> Diese Sektion dokumentiert den ursprünglichen Incus-Testbetrieb. Zora läuft heute auf Proxmox.
> Aktueller Stand: `SSoT_Konfigurations-Masterplan_Zora.md`

# Infrastruktur-Dokumentation: Incus Virtualisierung (HISTORISCH)

## 1. Virtualisierungs-Strategie

Einsatz von Incus (LXC-Fork) zur Bereitstellung isolierter System-Container.

## 2. Netzwerk-Infrastruktur (`incusbr0`)

### 2.1 Technische Konfiguration

* **Subnetz:** 10.0.6.1/24.
* **Modus:** Managed Bridge.
* **Einschränkung:** `ipv4.firewall: "false"`.

## Netzwerk-Konfiguration (`incusbr0`)
* **Subnetz:** 10.0.6.1/24
* **Firewall-Management:** Deaktiviert (`ipv4.firewall=false`), um Kernel-Fehler (`xt_CHECKSUM`) zu umgehen.
* **Erstellung:** `incus network create incusbr0 ipv4.address=10.0.6.1/24 ipv4.nat=true ipv4.firewall=false ipv6.address=none`

### 2.2 Analyse des Ausschlussverfahrens

Ursprünglich schlug die Erstellung der Brücke fehl (`exit status 1: Extension CHECKSUM revision 0 not supported`). 

* **Versuch A (Standard):** Incus verwaltet Firewall. -> **Fehlgeschlagen** (Kernel-Modul fehlt).
* **Versuch B (Bypass):** Incus erstellt nur das Interface, Administrator verwaltet Firewall manuell. -> **Erfolgreich**.

## 3. Port-Exposition via Proxy-Device

Anstatt Ports instabil über die IP-Adresse des Hosts zu binden, nutzt das Biest das native Incus-Proxy-Gerät:

```bash
incus config device add infra-gitea gitea-proxy proxy listen=tcp:0.0.0.0:3000 connect=tcp:127.0.0.1:3000
```

Vorteil: Der Dienst ist unter localhost:3000 erreichbar, selbst wenn sich die interne Container-IP ändert.

## 4. Administration der Web-UI

* **URL:** https://localhost:8443.
* **Sicherheit:** Zugriff nur via TLS-Client-Zertifikat. Das Zertifikat muss im Browser-Keystore des Administrators hinterlegt sein.

## Web-UI (Incus Dashboard)
* **Zugriff:** `https://localhost:8443`
* **Authentifizierung:** TLS-Zertifikate (Client-Zertifikat im Browser importiert).
* **Token-Management:** Falls ein neuer Browser verbunden werden muss: `incus config trust add [Name]`.

## Proxy-Geräte (Port-Forwarding)
Um Dienste aus Containern auf dem Host verfügbar zu machen:
`incus config device add [Container] [Proxy-Name] proxy listen=tcp:0.0.0.0:[Host-Port] connect=tcp:127.0.0.1:[Container-Port]`

---

## 3. Gitea_Konfiguration&Bedienungsanleitung.md

# Anwendungs-Dokumentation: Gitea (MoCode)

## 1. Instanz-Details

* **Container-Name:** `infra-gitea`.
* **Software-Version:** 1.21.4 (ARM64 Binary).
* **Betriebs-User:** `git` (Heimatverzeichnis: `/home/git`).

## Container-Setup
* **Name:** `infra-gitea`
* **Interne IP:** 10.0.6.159
* **Betrieb als:** User `git` (UID 101)

## 2. Speicher-Architektur & FHS-Konformität

Um Datenverlust bei Updates zu vermeiden, werden alle persistenten Daten außerhalb des Programmverzeichnisses (`/usr/local/bin`) gespeichert:

* **WorkPath (GITEA_WORK_DIR):** `/var/lib/gitea`.
* **Repositories:** `/var/lib/gitea/data/gitea-repositories`.
* **Datenbank:** SQLite3 (`/var/lib/gitea/data/gitea.db`).

## 3. Prozess-Management ("Gradle-Style" Troubleshooting)

Aufgrund der engen Kopplung zwischen Gitea und dem SSH-Daemon kann es zu blockierten Sockets kommen.
**Fehlersymptom:** `bind: address already in use`.
**Lösungsschritte (Hard Reset):**

1. `pkill -9 -u git` (Beendet alle Instanzen des Users).
2. `fuser -k 3000/tcp` (Erzwingt Freigabe des Ports).
3. `systemctl restart gitea` (Sauberer Neustart via Systemd).

## 4. Systemd-Service Konfiguration

Der Dienst wird über eine spezialisierte Unit-Datei gesteuert, die den `WORK_DIR` Fehler umgeht:

```ini
[Service]
Environment=GITEA_WORK_DIR=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /var/lib/gitea/custom/conf/app.ini
User=git
Restart=always
```

## 5. Sicherheits-Audit

* **Registrierung:** Deaktiviert (Private Instanz).
* **Sichtbarkeit:** "Ansehen erfordert Anmeldung" ist aktiv.
* **SSH:** Port 2222 (Vermeidung von Kollisionen mit Host-Port 22).

### Zusammenfassung der Architektur-Vorteile:

Durch diese Konfiguration ist das System **"Biest-sicher"**:

1. **Isolation:** Gitea kann das Host-System nicht kompromittieren.
2. **Pfad-Treue:** Updates der Binary beeinflussen die Datenbank nicht.
3. **Resilienz:** Dank Systemd startet Gitea nach jedem Absturz oder Reboot innerhalb von 2 Sekunden automatisch neu.

## Pfade & Verzeichnisse (Wichtig!)
Daten werden konsequent unter `/var/lib/gitea` gespeichert, um System-Verzeichnisse sauber zu halten:
* **Programm:** `/usr/local/bin/gitea`
* **Konfiguration:** `/var/lib/gitea/custom/conf/app.ini`
* **Repositories:** `/var/lib/gitea/data/gitea-repositories`
* **Datenbank:** `/var/lib/gitea/data/gitea.db` (SQLite3)
* **LFS-Pfad:** `/var/lib/gitea/data/lfs`

## Netzwerkzugriff
* **Web-Interface:** Port 3000 (auf Host gemappt via Incus-Proxy).
* **SSH-Port:** 2222 (um Konflikte mit Host-SSH zu vermeiden).

## Systemd-Autostart
Gitea wird als Hintergrunddienst im Container verwaltet:
* **Service-Datei:** `/etc/systemd/system/gitea.service`
* **Besonderheit:** `GITEA_WORK_DIR=/var/lib/gitea` muss gesetzt sein, um Permission-Fehler in `/usr/local/bin` zu vermeiden.

## Wartung & Fehlerbehebung
* **Status prüfen:** `systemctl status gitea` (im Container)
* **Hängende Prozesse killen:** `pkill -u git` oder `fuser -k 3000/tcp`
* **Gezielter Neustart:** `systemctl restart gitea`