openvox-docker/README.md

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
• Manuelle Inbetriebnahme
• Automatisierte Inbetriebnahme mit Ansible
• Neuen Puppet-Agenten verbinden
• 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.

   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.

   # Im Hauptverzeichnis des Projekts ausführen:
   sudo mkdir -p ./ca_data
   sudo chown -R 999:999 ./ca_data
   

4. Services starten:

   docker compose up -d
   

5. Status überprüfen: Nach etwa einer Minute sollte der openvox-Container als healthy angezeigt werden.

   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:

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

   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 oder 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 aus, und Ihr Puppet-Master ist mit allen signierten Zertifikaten wieder online.