# Dockerized Puppet Master (OpenVox)

Dieses Projekt konfiguriert einen Puppet Master, der in Docker-Containern läuft. Es verwendet Docker Compose für die Orchestrierung der Dienste, einschließlich des Puppet Masters (`openvox`), einer PostgreSQL-Datenbank und anderer notwendiger Komponenten.

Die Konfiguration wurde optimiert, um portabel und einfach auf neuen Servern ausrollbar zu sein.

## Inhaltsverzeichnis

- [Verzeichnisstruktur](#verzeichnisstruktur)
- [Manuelle Inbetriebnahme](#manuelle-inbetriebnahme)
- [Automatisierte Inbetriebnahme mit Ansible](#automatisierte-inbetriebnahme-mit-ansible)
- [Neuen Puppet-Agenten verbinden](#neuen-puppet-agenten-verbinden)
- [Backup & Portabilität](#backup--portabilität)

---

## Verzeichnisstruktur

- `docker-compose.yml`: Die zentrale Datei, die alle Docker-Services, Volumes und Netzwerke definiert.
- `.env.example`: Eine Vorlagedatei, die zeigt, welche Umgebungsvariablen (z.B. Passwörter) in einer `.env`-Datei benötigt werden.
- `.gitignore`: Definiert Dateien und Verzeichnisse, die von Git ignoriert werden sollen (z.B. `ca_data/`, `.env`).
- `code/`: Enthält den Puppet-Code (Manifeste, Module etc.), der von den Agenten angewendet wird.
- `config/`: Beinhaltet Konfigurationsdateien für die verschiedenen Dienste.
- `ca_data/`: **Wichtiges Verzeichnis.** Dies ist ein persistenter Speicher für die Certificate Authority (CA) des Puppet Masters. Es enthält alle signierten Zertifikate und wird per "bind mount" eingebunden.
- `hiera_config.md`: Erklärt die Konfiguration von Hiera, dem Key-Value-Lookup-System von Puppet, das hier zur Klassenzuweisung verwendet wird.
- `openvox_bugs.md`: Dokumentiert häufige SSL-Fehler und deren Lösungen.
- `deploy_openvox.yml`: Ein Ansible-Playbook, um das lokale Setup zu automatisieren.

---

## Manuelle Inbetriebnahme

Um das Projekt auf einem neuen Rechner (mit installiertem Docker und Docker Compose) zum ersten Mal manuell zu starten:

1.  **Projektverzeichnis klonen/kopieren:**
    Stellen Sie sicher, dass Sie das gesamte Projektverzeichnis auf dem neuen Host haben.

2.  **`.env`-Datei erstellen:**
    Kopieren Sie die Vorlagedatei und tragen Sie Ihr sicheres Passwort ein.
    ```bash
    cp .env.example .env
    # Bearbeiten Sie nun die .env-Datei und setzen Sie das Passwort.
    ```

3.  **CA-Verzeichnis erstellen und Berechtigungen setzen (Der "CA-Fehler")**
    Der Puppet-Server im Container läuft aus Sicherheitsgründen nicht als `root`, sondern als Benutzer `puppet` mit der User-ID (UID) `999`. Wenn Docker ein Verzeichnis für einen "bind mount" verwendet, gehört dieses standardmäßig `root`. Dies führt zu einem "Permission denied"-Fehler.

    Um dies zu beheben, müssen wir das `ca_data`-Verzeichnis manuell erstellen und ihm die korrekten Berechtigungen geben, *bevor* der Container gestartet wird.
    ```bash
    # Im Hauptverzeichnis des Projekts ausführen:
    sudo mkdir -p ./ca_data
    sudo chown -R 999:999 ./ca_data
    ```

4.  **Services starten:**
    ```bash
    docker compose up -d
    ```

5.  **Status überprüfen:**
    Nach etwa einer Minute sollte der `openvox`-Container als `healthy` angezeigt werden.
    ```bash
    docker compose ps
    ```

---

## Automatisierte Inbetriebnahme mit Ansible

Das beiliegende Ansible-Playbook `deploy_openvox.yml` automatisiert die Schritte der manuellen Inbetriebnahme auf Ihrem lokalen Rechner.

### Lokale Ausführung (Standard)

**Voraussetzungen:**
- Ansible und die `community.docker`-Collection (`ansible-galaxy collection install community.docker`) müssen auf Ihrem lokalen Rechner installiert sein.
- Docker und Docker Compose müssen installiert sein.

**Ausführung:**

1.  **Playbook verschieben:**
    Das Playbook ist so geschrieben, dass es den `openvox`-Ordner als Unterverzeichnis erwartet. Verschieben Sie `deploy_openvox.yml` eine Ebene nach oben:
    ```bash
    # Im Verzeichnis /home/jonnybravo/.docker/openvox/ ausführen
    mv deploy_openvox.yml ../
    ```

2.  **`.env`-Datei erstellen:**
    Stellen Sie sicher, dass die `.env`-Datei mit dem Passwort existiert, wie im manuellen Setup beschrieben.

3.  **Playbook starten:**
    Führen Sie das Playbook vom übergeordneten Verzeichnis aus (`/home/jonnybravo/.docker/`). Es führt die `mkdir`-, `chown`- und `docker compose up`-Schritte für Sie aus.
    ```bash
    ansible-playbook deploy_openvox.yml
    ```

### Option: Remote-Deployment

Obwohl das Playbook für den lokalen Gebrauch optimiert ist, kann es als Vorlage für ein Remote-Deployment dienen. Dazu müssten Sie es anpassen, um:
1.  Eine `hosts`-Variable anstelle von `localhost` zu verwenden.
2.  Einen `copy`-Task hinzuzufügen, der das Projektverzeichnis auf den Zielserver kopiert.
3.  Sicherzustellen, dass die Pfadvariablen (`project_path`) für den Remote-Kontext korrekt sind.

---

## Neuen Puppet-Agenten verbinden

Unabhängig von der Installationsmethode ist der Prozess zum Verbinden eines neuen Agenten immer gleich:

1.  **Auf dem neuen Agenten:** `sudo puppet agent -t` (wird fehlschlagen)
2.  **Auf dem Docker-Host (Master):** `docker exec -it openvox puppetserver ca sign --certname <agent_hostname>`
3.  **Erneut auf dem Agenten:** `sudo puppet agent -t` (sollte erfolgreich sein)

*Bei SSL-Problemen siehe `openvox_bugs.md`.*

---

## Backup & Portabilität

Durch die Verwendung eines "bind mounts" für das `ca_data`-Verzeichnis ist das Projekt hochgradig portabel und einfach zu sichern.

- **Backup:** Sichern Sie einfach den gesamten `openvox`-Projektordner. Alle wichtigen Daten (Puppet-Code, CA-Zertifikate, `.env`-Datei) sind darin enthalten.
- **Wiederherstellung/Umzug:** Kopieren Sie den Ordner auf einen neuen Server, führen Sie die Schritte unter [Manuelle Inbetriebnahme](#manuelle-inbetriebnahme) oder [Automatisierte Inbetriebnahme mit Ansible](#automatisierte-inbetriebnahme-mit-ansible) aus, und Ihr Puppet-Master ist mit allen signierten Zertifikaten wieder online.

    Das Playbook kopiert den `openvox`-Ordner nach `/opt/openvox` auf dem Zielserver, setzt die Berechtigungen und startet die Container.

---

## Backup & Portabilität

Durch die Verwendung eines "bind mounts" für das `ca_data`-Verzeichnis ist das Projekt hochgradig portabel und einfach zu sichern.

- **Backup:** Um ein vollständiges Backup zu erstellen, sichern Sie einfach den gesamten `openvox`-Projektordner. Alle wichtigen Daten (Puppet-Code, CA-Zertifikate) sind darin enthalten.
- **Wiederherstellung/Umzug:** Kopieren Sie den gesicherten Ordner auf einen neuen Server, führen Sie die Schritte unter [Lokale Inbetriebnahme](#lokale-inbetriebnahme) aus, und Ihr Puppet-Master ist mit allen signierten Zertifikaten wieder online.