← zur Übersicht

Wegweiser durch das Projekt — welches Dokument, welcher Ordner, welcher Befehl


titel: Wegweiser durch das Projekt — welches Dokument, welcher Ordner, welcher Befehl

erstellt: 2026-10-31

status: laufend gepflegt; bei jeder Änderung am Aufbau aktualisieren

betrifft: das ganze Projekt Ansible-Serveraufbau

tags: [index, wegweiser, betrieb, dokumentation]


Wegweiser — was liegt wo, was gilt

Diese Datei ist der Einstieg. Wer in drei Monaten einen Server neu bauen

oder einen Fehler suchen will, liest zuerst hier und geht dann in das genannte

Dokument.

Stand: 31.10.2026. An diesem Tag wurde der Aufbau von Server 05

(Frageknopf/Meet) mit einem einzigen Knopf durchgezogen —

https://nunfragedocheinfach.ichselbstreal.site/, alle acht Schritte grün.


1. Wo liegt was

OrtInhalt
02-Projekte\Ansible-Serveraufbau\ (Vault, Windows)Das Projekt selbst: Playbooks, Vorlagen, Inventar, Dateien, Doku. Alles, was zählt.
…\playbooks\Die Playbooks (siehe Abschnitt 3)
…\inventory\produktion.ini (die echten Server), wegwerf.ini (Testserver)
…\files\, …\templates\, …\roles\Zutaten, die die Playbooks auf den Server bringen
…\docs\Die Dokumentation — Einstieg ist diese Datei
…\hilfsskripte\Einmalige Werkzeuge: Diagnosen, Reparaturen, Panel-Werkzeuge. Nichts davon ist für den Aufbau nötig (siehe hilfsskripte\README.md)
C:\vms\steuer127\web\index.htmlQuelltext des Steuerpanels (wird nach /var/www/steuer127/index.html kopiert)
steuer127 → /root/ansible-serveraufbau/Arbeitskopie des Projekts auf dem Steuerserver. Von hier läuft Ansible.
steuer127 → /home/steueruser1/panel/Das Panel: app.py (Flask), index.html, schritte/*.sh, logs/
steuer127 → /var/lib/steuer-panel/stand.jsonHäkchen-Stand der acht Schritte (überlebt einen Neustart)
steuer127 → /root/work/sicherungen/server05-komplett/s05komplett.tar.gzDas 14,8-MB-Paket mit App, Beratern, Diensten (Quelle für Schritt 5)
Zielserver (wegwerf-05-buttons)/opt/meeting-test (App), /root/meeting-test-agents (Berater), /root/avatar-keyframe/venv
C:\Backups\server05-komplett-20261029\Sicherung der Oberflächen-Dateien und Berater-Daten (Master-Kopien)

Merksatz: Das Vault ist die Wahrheit. steuer127 ist die Werkbank. Der

Zielserver ist wegwerfbar.


2. Welches Dokument wofür

DokumentThemaWann lesen
README.mdGrundsatzentscheidung (Ansible statt Skripte) und Projektstrukturbeim Einstieg ins Projekt
docs\26-SERVER-LISTE.mdWer läuft wo: alle Server mit ID, Diensten, Ansible-Stand und der Reihenfolge der nächsten Aufbautenwenn die Frage „was haben wir eigentlich" auftaucht
docs\27-SERVER08-WIEDERAUFBAU.mdServer 08 (VPN/headscale) neu aufbauen: Sicherung, Playbook, geprüfte Ergebnisse, vier gefundene Fehlerwenn 08 wiederhergestellt wird
docs\28-SERVER01-WIEDERAUFBAU.mdServer 01 (LiveKit/Telefonie) neu aufbauen: 82-MB-Paket, Playbook, Test-Ergebnisse, fehlende Bibliothekenwenn 01 wiederhergestellt wird
docs\29-SERVER03-WIEDERAUFBAU.mdServer 03 (Nextcloud + Avatar) neu aufbauen: 1,1-GB-Paket + 4,3-MB-Datenbankabzug, Playbook, geprüfte Ergebnissewenn 03 wiederhergestellt wird
docs\30-PANEL-STREAKS.mdPanel steuer127: Aufbau, Rezept für einen weiteren Server, sieben Fallen, Prüfbefehlewenn im Panel etwas klemmt oder ein Server dazukommt
docs\31-SERVER05-STILLLEGEN.mdServer 05 abschalten und zurückholen: was gesichert ist, der Rückweg in fünf Schritten, was danach anders istwenn 05 gelöscht wird oder zurück soll
docs\belege\Protokolle echter Läufe als Beweis (z. B. der Ruck-Zuck-Lauf von 13 am 31.10.)wenn jemand sehen will, dass es wirklich lief
docs\19-SERVER05-VON-NULL-MIT-ANSIBLE.mdDie Hauptanleitung: acht Schritte, Zeiten, alle Fallen des ersten Durchgangswenn Server 05 neu gebaut wird
docs\18-ANTWORT-PANEL-UND-SPRECHANZEIGE.mdAntwort-Panel, Sprecher-Anzeige, Pegel, Doppel-Sprechenwenn die Oberfläche klemmt
docs\20-SZENARIEN-BERATERRUNDE.mdDie sechs Szenarien (Aus / Alle / TV-Runde / Pro-Contra / Fazit / Risiko)vor einer Beraterrunde
docs\21-NAECHSTER-AUFBAU-PERFORMANCE.mdSpeicher und Antwortzeit: was beim nächsten Mal besser wirdvor dem nächsten Aufbau, beim Planen
docs\22-WER-HOERT-ZU.mdWer hört zu: warum ein Berater erst nach einem Klick zuhört, und die drei Verbesserungswege (Namensansprache)wenn „er hört mich nicht" auftritt
docs\23-SERVER09-AUDIO-NEUAUFBAU.mdServer 09 (Audio/Telefon) neu aufbauen: Playbook, Panel-Weg, fünf Fehler des ersten Laufswenn 09 wiederhergestellt wird
docs\17-WEGWERF-WIEDERAUFBAU-05-ECHT.mderster echter Durchlauf (90 Minuten, 6 Fallen)zum Nachlesen, was schon weh tat
docs\16-SERVER05-EXTERN-NEU-AUSSETZEN.mdPaketbau und Ablauf ohne Panelwenn das Panel nicht erreichbar ist
docs\02-mail.mdMailserver (Postfach-Datenbank, Dovecot, Rspamd)wenn Mail nicht ankommt
docs\12-LIVEKIT-LOKAL.mdLiveKit lokal statt Cloudwenn Gespräche nicht zustande kommen
docs\04-STEUER127.md, 05-ANLEITUNG-127.mdSteuerserver selbst aufbauenwenn steuer127 neu muss
docs\11-SERVER05-LOKAL-BUTTONS.mdder lokale Nachbau auf steuer127wenn lokal getestet wird
docs\13/14/15-…Wegwerf-Wiederaufbau von Server 01 / 05 / 09als Muster für andere Server

Ältere Dokumente (01–12) beschreiben den Weg vor der

Ansible-Entscheidung. Sie sind gültiges Wissen über die Server, aber nicht mehr

die Arbeitsanweisung.


3. Welches Playbook was tut

PlaybookTutHostsWichtigste Tags
00-server-anlegen.ymllegt einen Wegwerfserver bei Hetzner an (Name muss mit wegwerf- beginnen), hängt die freie Primary IP anlocalhost—
00b-dns.ymlsetzt/entfernt einen A-Eintrag über die Namecheap-API — läuft auf dem Mailserver, weil Namecheap die API nur von dort erlaubtmail— (dns_name, dns_ip, dns_sld, dns_tld, dns_modus)
01b-mailkonto.ymlstellt ein Postfach sicher: Zone + Konto in der vmail-Datenbank, Passwort, Postfachordner, Testmailmail— (-e @/root/testzugang.yml)
05-buttons.ymlder eigentliche Aufbau von Server 05 in neun PhasenZielserverpakete, node, dateien, bauen, python, dienste, webserver, zertifikat, mail, abnahme
09-audio.ymlAufbau von Server 09 (Audio/Telefon, xAI realtime) in sieben PhasenZielserverpakete, node, dateien, dienste, webserver, zertifikat, abnahme
09b-audio-code.ymlCode-Update einer laufenden 09: tauscht nur server.js, admin-extra.js, package.json, app.js, index.html, admin.html (Sicherung .vor-code-<stempel>, Syntaxprüfung, Marker, Neustart, Abnahme). .env und /var/lib bleiben unangetastet — genau dafür ist es da. Aufruf: -i inventory/produktion.ini -l 09-audio -e "domain=voice.avatarneu.unsere-ki-runde.xyz"laufende 09keine (ein Rutsch)
08-headscale.ymlAufbau von Server 08 (VPN/headscale) aus der Sicherung: Docker, drei headscale-Instanzen, drei headplane, privyx/formular/openwebui, nginx, Zertifikate. Baut immer mit Daten — nie leer. Testweise -e "mit_webserver=false mit_zertifikat=false"Zielserverpakete, dateien, dienste, webserver, zertifikat, abnahme
01-livekit.ymlAufbau von Server 01 (LiveKit + SIP + redis + token-server) aus dem 82-MB-Paket. Stufe 2 (Python-Agenten, Frontend-Build) über -e mit_agenten=trueZielserverpakete, dateien, dienste, agenten, webserver, zertifikat, abnahme
06-gateway.ymlAufbau von Server 06 (Bastion ins lokale Netz): vier WireGuard-Tunnel, nginx (meet-lokal, livekit-lokal, mcp), Firewall-Regeln. Schalter: mit_tunneln, mit_ufw, ssh_vonZielserverpakete, dateien, dienste, ufw, webserver, abnahme
02-mail.ymlAufbau von Server 02 (Mailserver): MariaDB

mail, Dovecot (IMAP/LMTP/Sieve), rspamd mit DKIM, Postfix, redis, nginx. Setzt den Benutzer

mail mit UID 1009 vor dem Entpacken an, sonst gehören die Maildirs niemandem. Schalter: mit_webserver, mit_zertifikat | Zielserver | pakete, dateien, dienste, webserver, zertifikat, abnahme |

03-nextcloud.ymlAufbau von Server 03 (Nextcloud 34 + Avatar-Beratung) aus Paket und Datenbankabzug: MariaDB, PHP 8.3-FPM, redis, postfix, nextcloud, avatar-ai (pm2), nginx, Zertifikate. Datenbank-Zugang wird aus config.php gelesenZielserverpakete, dateien, dienste, agenten, webserver, zertifikat, abnahme
99-wegwerf-loeschen.ymllöscht einen Wegwerfserver über die Hetzner-APIlocalhost—
10-lernschritte.ymlkleine Lernschritte für den Katalog im PanelZielserververschiedene
01-steuerserver.ymlbaut steuer127 selbststeuerserver—

Wichtige Variablen in 05-buttons.yml:

VariableBedeutungVorgabe
domainName, unter dem der Server erreichbar istmuss mitgegeben werden
namen_suffixtrennt Raumnamen (…541w), damit zwei Server nicht um dieselben Berater-Jobs streitenleer
schutzPasswortschutz der ganzen Seiteautomatisch: aus, wenn wegwerf im Namen steht, sonst an
schutz_adminPasswortschutz der Verwaltung /meeting-adminimmer an
berater_last_schwelleab welcher Last ein Berater-Worker sich als belegt meldet3.0
berater_reserve_prozessevorgewärmte Prozesse je Berater0 (4-GB-Server), auf 8 GB wieder 1
protokoll_empfaengerStandard-Adresse im Feld „Meine E-Mail-Adresse"leer (dann bleibt der Code-Wert)

4. Der Weg mit einem Knopf (Ruck-Zuck)

Im Panel: https://steuer127.g3.local/ → links „Server neu mit Ansible" →

„10 · Ansible-Lehrweg" → Domain und E-Mail eintragen → **⏩ Ruck-Zuck: alle acht

Schritte**.

Der Knopf startet /home/steueruser1/panel/schritte/neu05-alles.sh; das Skript

ruft nacheinander dieselben acht Schritt-Skripte auf, die auch die einzelnen

Knöpfe starten. Es wartet nach Schritt 1 auf SSH und nach Schritt 2, bis die

Welt den Namen sieht (höchstens 15 Minuten, einstellbar über WARTE_MIN).

Auf der Kommandozeile dasselbe:


cd /root/ansible-serveraufbau
ansible-playbook playbooks/00-server-anlegen.yml -i inventory/wegwerf.ini \
  -e "name=wegwerf-05-buttons" -e "primary_ip_id=157551658"

# DNS: der Name ohne Zone, die Zone als SLD/TLD
ansible-playbook playbooks/00b-dns.yml -i inventory/produktion.ini \
  -e "dns_name=nunfragedocheinfach" -e "dns_sld=ichselbstreal" -e "dns_tld=site" \
  -e "dns_ip=142.132.172.245" --vault-password-file /root/.vault_pass2.txt

# Aufbau, Schritt für Schritt
ansible-playbook playbooks/05-buttons.yml -i inventory/wegwerf.ini \
  -l wegwerf-05-buttons \
  -e "domain=nunfragedocheinfach.ichselbstreal.site" -e "namen_suffix=w" \
  --tags pakete        # dann node, dateien, bauen,python,dienste, webserver,zertifikat, abnahme

Achtung: Schritt 6 immer mit allen drei Tags (bauen,python,dienste) —

ohne python starten die Dienste nicht (status=203/EXEC).

Für Server 09 (Audio) derselbe Weg mit acht Schritten, Sammellauf

neu09-alles.sh. Er nimmt zwei Angaben aus der Umgebung — genau die zwei

Felder, die im Panel vor dem Start eingetragen werden:


NEUE_DOMAIN=audio-wegwerf.ichselbstreal.site \
PROTOKOLL_EMPFAENGER=info@ichselbstreal.site \
  bash /home/steueruser1/panel/schritte/neu09-alles.sh
# Wiederaufnahme nach einem Fehler: VON=3 … (BIS=5 für einen Testlauf)

Schritt 8 prüft seit dem 31.10. den Inhalt, nicht nur den Dienst: Suchpfad,

fenster-Fix, Quellennamen, Aufnahme, Verwaltung, 14 Rollen, Seiten, Schlüssel

sowie je einen echten Aufruf von /api/session und /api/websearch. Schlägt

der Sitzungs-Token fehl, steht die Ursache im Klartext da (meist xAI-Guthaben).

Vault-Passwort steht zentral in ansible.cfg (vault_password_file).


5. Postfach für eine neue Domain


ansible-playbook playbooks/01b-mailkonto.yml -i inventory/produktion.ini \
  -e @/root/testzugang.yml --vault-password-file /root/.vault_pass2.txt

/root/testzugang.yml ist verschlüsselt (ansible-vault, Passwort

/root/.vault_pass2.txt) und enthält mail_konto, mail_passwort,

protokoll_empfaenger. Das Playbook legt Zone und Konto an, setzt das Passwort,

legt den Postfachordner an und schickt eine Testmail.

Was dabei gelernt wurde: die vmail-Datenbank liegt unter

/var/vmail/mailboxes/<domain>/<user>/mail/… (Dovecot: maildir:~/mail), nicht

unter /var/mail/vhosts. Der Datenbank-Benutzer vmail darf nur lesen —

Schreiben braucht den Verwalter-Zugang (mysql_root_password, im Vault

/root/mailonly1_vault.yml, am 31.10. neu gesetzt).


6. Zugangsdaten und Tresore

WasWoPasswort
Hetzner-API/root/.hcloud_env auf steuer127 (eine Zeile!)—
Namecheap-API + Mailserver-Werte + MySQL-root/root/mailonly1_vault.yml (verschlüsselt)/root/.vault_pass2.txt
Testwerte (Postfach, Protokolladresse)/root/testzugang.yml (verschlüsselt)/root/.vault_pass2.txt
SSH zu den Servern~/.ssh/server1 (root, Port 22), ~/.ssh/anna2 (anna2, Port 2121)—
SSH zum SteuerserverWindows: C:\Users\pc2\.ssh\steuer → steueruser1@192.168.0.127—
Panel-Anmeldung (Lernserver)Browser-Passwortmanager: besucher / adminÜbergangs-Passwörter, vor Echtbetrieb ändern

Regel: Keine Passwörter in Dokumente schreiben. Werte gehören in einen

Vault, die Dokumente nennen nur den Ort.


7. Aufräumen nach dem Test

neu05-snapshot.sh): sichert den Stand, kostet ~0,012 € je GB und Monat.

DELETE /servers/<id>; die Primary IP 142.132.172.245

(primary_ip_id 157551658) bleibt frei für den nächsten Aufbau.

nächsten Aufbau wiederverwendet (spart die Wartezeit).


8. Fallen, die schon Geld und Zeit gekostet haben

Kurzfassung; ausführlich in docs\19-… und docs\17-…:

löschte advisors.json / knowledge-categories.json. Jetzt rsync mit

--exclude und force: false.

Schritt 6 braucht bauen,python,dienste zusammen.

…unsere-ki-runde.xyz) → neun sinnlose Warteversuche. Jetzt dns_fqdn.

Namen abgeleitet; die Verwaltung ist immer geschützt.

/meeting-admin/categories — lag hinter dem Verwaltungs-Passwort. Jetzt

öffentlich (exakter location-Treffer), Verwaltung bleibt zu.

Worker meldeten „full capacity", LiveKit schickte niemanden; (b) die Route

merkte sich die Anforderung und löschte sie nie → beim zweiten Beitreten

wurde nie wieder angefordert.

stdbuf -oL -eL; stand.json lag als root da → Besitzer korrigiert.

dem Verbindungstest.

im catch-Rückruf von melde() statt oben in der Datei → jedes

Spracht-Ereignis brach mit ReferenceError ab, die Seite blieb stumm

(„Grok hat den Sprachstart nicht innerhalb von 20 Sekunden bestätigt"), obwohl

Server und xAI fehlerfrei antworteten. Merke: Bei „es passiert nichts" im

Browser zuerst unhandledrejection/error-Zuhörer setzen und die Konsole

lesen — nicht am Server suchen. Siehe docs\23-… Teil 4.

(/opt/grok-audio-voice, /var/www/grok-audio-voice). Ein verschachteltes

ssh … "sudo python3 -" lief deshalb schon zweimal lokal. Jetzt: Skript per

scp auf das Ziel legen, dort starten, und **im Skript zuerst hostname

ausgeben**. Vorlage: hilfsskripte\lage-09-service.sh.


9. Offene Punkte

Schlüssel ist gültig, aber das Konto ist am Monatslimit:

HTTP 403 … used all available credits or reached its monthly spending limit

(Team a63b36f3-828d-426b-91fd-44cf067e4da1). Betroffen sind beide

Server: Produktion voice.avatarneu.unsere-ki-runde.xyz und der

Wegwerfserver. Aufladen auf https://console.x.ai → Billing, danach genügt

Schritt 8 (VON=8) zur Kontrolle — nichts neu bauen.

hört ein Berater erst nach einem Klick zu. Weg B (ein Berater hört immer mit

und gibt an den genannten weiter) ist beschlossen, aber noch nicht gebaut —

sinnvoll zusammen mit dem Wechsel auf cx33.

Thread-Ausführung, zram, Servertyp cx33 (8 GB, 10,19 € statt 6,59 €).

statt 60 s).

als „laeuft" angezeigt (nur Anzeige, der Lauf ist davon nicht betroffen).

Ausgabe live, die Datei hinkt nach.

Testwerte ersetzen, sobald der Server echt genutzt wird.

Server nicht mehr existiert und die IP inzwischen Wegwerfservern gehört).

bei Hetzner (zusammen ~155 GB, ~1,85 €/Monat) — prüfen und alte löschen.

gehoben** (09b-audio-code.yml): Live-Recherche, Quellennamen statt Links,

fenster-Fix. Grenzen (5/Tag, 3/IP, 3 Min) und Profil blieben unverändert.

Rückweg: Sicherungen: *.vor-code-20261031-153317 auf dem Server, dazu

Snapshots 09-audio-zu-audio-vortausch-20261031-1525 (0,97 GB) und

wegwerf-09-audio-gut-20261031-1525 (1,29 GB), Dateisicherung

/root/work/sicherungen/09-audio/prod09-vor-umbau-20261031.tar.gz.

geprüft und um 15:56 gelöscht** (Server-ID 173780199); der A-Eintrag

audio-wegwerf.ichselbstreal.site ist um 16:01 aus der Zone entfernt

(Löschen braucht -e dns_min_eintraege=5, sonst bricht die Schutzprüfung ab:

die Zone ichselbstreal.site hat nur 10 Einträge, die Vorgabe ist 13).

Der Stand von vorher liegt als Snapshot wegwerf-09-audio-gut-20261031-1525.

Paket → Schritt 1–8. Vor jedem Eingriff in eine laufende 09: Snapshot

(Panel neu09-snapshot) und danach 09b-audio-code.yml für reine

Code-Änderungen.

panel/index.html wirken erst nach dem Kopieren dorthin.

startet nicht mehr, systemd dreht in einer Schleife. Nach jedem Patch

ast.parse und systemctl is-active prüfen. Siehe docs\30-….

ist falsch (Datei nicht ausführbar), richtig ist $(. …/neu03.env; echo $NAME).

Eintragen jede Zeile mit dem Namen entfernen, auch kommentierte.

Ubuntu 24.04 → …/linux/debian noble gibt es nicht. Im Playbook aus

ansible_distribution ableiten (docker_distro in 08-headscale.yml).

nicht ohne libsoxr0, libopus0, libopusfile0 — im Paket sind sie nicht.

Nach dem Einspielen ldd <programm> | grep "not found" prüfen.