# 📦 Strategische Integration von Butane & Ignition in NexusOS

> **Autor:** Markus Maiwald  
> **Mitwirkung:** Voxis / GPT DevMode  
> **Status:** Strategisch festgelegt  
> **Ziel:** Klare Einbindung von Butane und der Ignition Robotics Suite in das Entwicklungs- und Architekturmodell von NexusOS

---

## 🧭 Einleitung

**Butane** (YAML → Ignition JSON) und die **Ignition Robotics Suite** sind keine bloßen Nebenpfade. Sie sind strategische Komponenten, die zwei essenzielle Funktionen für NexusOS erfüllen:

1. **Deklarative Day-Zero-Provisionierung:** Butane liefert eine Blaupause für unsere eigene Konfigurationssprache und das Provisioning-System von NexusOS.
2. **Komplexe Build-Validierung:** Die Ignition Robotics Suite dient als realweltlicher "Torture Test" für den `nexus` Builder und die `.npk`-Architektur.

---

## 🔧 1. Butane & Ignition: Die Blaupause für deklarative Erstkonfiguration

### 💡 Problemstellung

Wie bringt man ein unverändertes ISO-Image bei seinem allerersten Boot in einen exakten, reproduzierbaren Zustand – ohne interaktive Eingaben oder nachgelagerte Skripte?

### ✅ Lösung & Integration in NexusOS

#### 📍 Phase 0–1: Sofortiger Einsatz von Butane

- Verwendung von `.bu`-Dateien (Butane YAML) zur Erstellung deterministischer Bootkonfigurationen
- Nutzung für Prototyping, Developer-VMs, QEMU-Bootszenarien
- `nexus build-image --provision-with ignition` erzeugt ISO/VM mit Provisioning-Config

#### 📍 Phase 2–4: Transpiler-Architektur – Butane als konzeptionelles Vorbild

- Entwicklung einer typ-sicheren, deklarativen EDSL `NimPak` (`system.nexus.nim`)
- Das native Tool `nexus` transpiliert `NimPak` nach Ignition JSON oder ein eigenes natives Format
- Ziel: Volle Kontrolle, Reproduzierbarkeit und Integration in CI/CD (`nexus system-image --target=gcp`)

#### 🛠️ Beispiel-Ziel-CLI:

```bash
nexus init --from-butane config.bu        # Migration vorhandener Konfigurationen
nexus system-image --target=gcp           # Generiert vollständiges System-Image inkl. Ignition-Config
```

#### 🌐 Cloud- & Bare-Metal-Usecase

- Kompatibilität zu CoreOS/Flatcar beibehalten

- Strategie zur Skalierung in Plattformen wie "IT Qube" oder beliebige Cloud-Flotten

---

## 🧪 2. Ignition Robotics Suite: Der kanonische Testfall für `.npk` & `nexus`

### 🎯 Ziel

Validierung der NexusOS Build-Toolchain an einem realweltlichen, hochkomplexen Open-Source-Stack (Ignition Gazebo).

### 🔬 Integration & Nutzen

| Paket               | Nutzen für NexusOS                                       |
| ------------------- | -------------------------------------------------------- |
| `ignition-gazebo`   | Tiefes Abhängigkeitsnetzwerk, ideal als Build-Stresstest |
| `ignition-tools`    | Leichtgewichtig, für erste Tests & CI geeignet           |
| `ignition-validate` | Validator-Logik für unsere `.npk-specs/schema.yaml`      |

### 📍 Testziele:

- Prüfung von `nimplates` für komplexe CMake-Projekte

- Reproduzierbare Builds via `nip build` & `nip verify`

- Showcase: „Wenn NexusOS diesen Stack besser paketiert als AUR oder Debian, haben wir gewonnen.“

---

## 🔗 Strategische Roadmap-Zuordnung

| Phase | Komponente          | Aktion                                                   |
| ----- | ------------------- | -------------------------------------------------------- |
| 0–1   | Butane              | Nutzung als Day-Zero-Provisionierung für ISO/VM-Tests    |
| 2     | ignition-tools      | Erste `.npk`-Pakete, Tests mit `nip`                     |
| 3     | ignition-validate   | Einbindung in Schema- und Validierungslogik              |
| 3–4   | `nexus` Provisioner | Entwicklung von `NimPak` + Transpiler nach Ignition JSON |
| 4     | ignition-gazebo     | Showcase für kompletten, komplexen Stack in NexusOS      |

---

```mermaid
graph LR
    A[Endbenutzer/Admin] --> B(Admin Dashboard Frontend - Vue3)
    B --> C(Core Backend API - Go)
    C --> D(Workflow Engine - Temporal.io)
    C --> E(PostgreSQL Datenbank - State, Config, Audit)
    C --> F(Secrets Management - HashiCorp Vault)

    D -- Triggers Tasks --> G(Go Backend Worker)

    G -- Uses Client --> H(M365 Graph API Client - Go SDK)
    G -- Uses Client --> I(Google Workspace API Client - Go SDK)
    G -- Uses Client --> J(Zitadel API Client - Go)
    G -- Executes --> K(OpenTofu Wrapper - Go)
    G -- Executes --> L(Helm Wrapper - Go SDK/CLI)
    G -- Interacts --> M(Kubernetes Client - client-go)

    H --> N(Microsoft 365 Tenant API)
    I --> O(Google Workspace Tenant API)
    J --> P(Zitadel Identity Platform)
    K -- Manages --> Q(Cloud Resources - DBs, Storage etc.)
    L -- Deploys/Manages --> R(Deployed Apps on K8s - Nextcloud etc.)
    M -- Interacts --> S(Kubernetes Cluster API - Talos)
    P -- IdP/Broker for --> R
    P -- External IdP --> N
    P -- External IdP --> O

    style F fill:#f9d,stroke:#333,stroke-width:2px
    style D fill:#ccf,stroke:#333,stroke-width:2px
    style P fill:#ccf,stroke:#333,stroke-width:2px
    style S fill:#d9ead3,stroke:#333,stroke-width:2px
    style Q fill:#d9ead3,stroke:#333,stroke-width:2px
    style R fill:#d9ead3,stroke:#333,stroke-width:2px
```
---
Here’s a structured **Phased Replacement Plan** for how NexusOS evolves from using **Butane + Ignition** to developing and owning a **fully native declarative provisioning system**, while maintaining compatibility.

## 📈 **Phased Replacement Plan: Butane & Ignition → NexusOS Native Provisioning**

```mermaid
graph TD
    A[Phase 0–1: Bootstrap with Butane + Ignition] --> B[Phase 2: NexusOS Provisioning DSL]
    B --> C[Phase 3: Native Transpiler (nexus → ignition.json)]
    C --> D[Phase 4: Native Executor Replacing Ignition]
    D --> E[Phase 5: Portable Nexus Provisioner + Compatibility Layer]
```

---

## 🧩 Phase Overview

### 🔹 **Phase 0–1: Bootstrap using Butane + Ignition**

> *“Don’t reinvent yet — just boot.”*

* Use official `butane` CLI to define `.bu` YAML
* Transpile to `.ign` JSON files
* Embed Ignition JSON in LiveCD initramfs or pass via GCP/EC2 metadata
* NexusOS boots and provisions using upstream Ignition binary

✅ **Fast path to bootable ISO & reproducible setup**

---

### 🔹 **Phase 2: Develop the `NimPak` Provisioning DSL**

> *“Replace the input language, not the backend.”*

* Define system in a type-safe EDSL (`system.nim`)
* Add standard building blocks (users, files, services, systemd units, filesystems)
* DSL compiles to internal AST (not yet targeting JSON)

✅ **Begin shaping our own syntax & abstraction model**

---

### 🔹 **Phase 3: Write Native Transpiler (`nexus provision --ignition`)**

> *“Generate compatible `.ign` JSON from `system.nim`.”*

* Translate `system.nim` → `.ign` JSON via native Nim transpiler
* Ensure full compatibility with existing Ignition-based systems
* Enables complete replacement of Butane

✅ **Drop Butane, NexusOS now controls all authoring & config generation**

---

### 🔹 **Phase 4: Native Executor replaces Ignition**

> *“Replace the runtime engine with our own init hook.”*

* Implement minimal executor in early userland (e.g. Toybox init or custom Nim binary)
* Reads `provision.npk.json` or `system.nim` AST directly
* Applies provisioning actions: file writes, user setup, fstab, etc.

✅ **No dependency on upstream Ignition; fully Nexus-native**

---

### 🔹 **Phase 5: Nexus Provisioner (Universal Init + Translator)**

> *“Support both NexusOS and compatible systems.”*

* `nexus provision --target flatcar` or `--target ignition` produces compatible `.ign` JSON
* Provide `nexus-init` binary: tiny FOSS init-time runner usable on other distros (optional)
* Portable across cloud platforms, edge, or bare-metal

✅ **Becomes provisioning standard for deterministic OS deployment across systems**

---

## 🔄 Feature Matrix by Phase

| Feature                         | Phase 0–1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 |
| ------------------------------- | --------- | ------- | ------- | ------- | ------- |
| Use of Butane                   | ✅         | ✅       | ❌       | ❌       | ❌       |
| Use of Ignition runtime         | ✅         | ✅       | ✅       | ❌       | ❌       |
| Own DSL for system config       | ❌         | ✅       | ✅       | ✅       | ✅       |
| Native provisioner logic        | ❌         | ❌       | ❌       | ✅       | ✅       |
| Backward compatibility (`.ign`) | ✅         | ✅       | ✅       | ✅       | ✅       |
| Cross-platform provisioning     | ❌         | ❌       | ❌       | ⚠️       | ✅       |

---

## 💡 Summary

NexusOS **initially leans on Butane and Ignition**, but with every phase:

* **More ownership is gained**
* **More abstraction power is unlocked**
* **More control over security, reproducibility, and provisioning logic is achieved**

By **Phase 5**, NexusOS becomes a **provisioning standard** itself — usable even outside NexusOS, similar to what Nix did with flakes and NixOps.

---

## 🧠 Fazit

Butane & Ignition sind **strategische Testfelder** und **Blaupausen**. Sie liefern einerseits sofortige Werkzeuge zur Provisionierung, andererseits die konzeptionellen Grundlagen für unsere eigene, überlegene Lösung.

Wenn NexusOS in der Lage ist:

- komplexe Systeme wie Ignition Robotics eleganter zu bauen, und

- Provisionierung genauso deterministisch wie eine Software-Build-Pipeline zu behandeln,

dann haben wir den Schritt vom klassischen Linux-Distro-Baukasten zu einer modernen, deklarativen OS-Plattform vollzogen.

---

> *"Wir bauen keine Distro. Wir bauen ein Betriebssystem, das sich selbst versteht."* 🐧