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]
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.
| Ort | Inhalt |
|---|---|
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.html | Quelltext 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.json | Häkchen-Stand der acht Schritte (überlebt einen Neustart) |
steuer127 → /root/work/sicherungen/server05-komplett/s05komplett.tar.gz | Das 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.
| Dokument | Thema | Wann lesen |
|---|---|---|
README.md | Grundsatzentscheidung (Ansible statt Skripte) und Projektstruktur | beim Einstieg ins Projekt |
docs\26-SERVER-LISTE.md | Wer läuft wo: alle Server mit ID, Diensten, Ansible-Stand und der Reihenfolge der nächsten Aufbauten | wenn die Frage „was haben wir eigentlich" auftaucht |
docs\27-SERVER08-WIEDERAUFBAU.md | Server 08 (VPN/headscale) neu aufbauen: Sicherung, Playbook, geprüfte Ergebnisse, vier gefundene Fehler | wenn 08 wiederhergestellt wird |
docs\28-SERVER01-WIEDERAUFBAU.md | Server 01 (LiveKit/Telefonie) neu aufbauen: 82-MB-Paket, Playbook, Test-Ergebnisse, fehlende Bibliotheken | wenn 01 wiederhergestellt wird |
docs\29-SERVER03-WIEDERAUFBAU.md | Server 03 (Nextcloud + Avatar) neu aufbauen: 1,1-GB-Paket + 4,3-MB-Datenbankabzug, Playbook, geprüfte Ergebnisse | wenn 03 wiederhergestellt wird |
docs\30-PANEL-STREAKS.md | Panel steuer127: Aufbau, Rezept für einen weiteren Server, sieben Fallen, Prüfbefehle | wenn im Panel etwas klemmt oder ein Server dazukommt |
docs\31-SERVER05-STILLLEGEN.md | Server 05 abschalten und zurückholen: was gesichert ist, der Rückweg in fünf Schritten, was danach anders ist | wenn 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.md | Die Hauptanleitung: acht Schritte, Zeiten, alle Fallen des ersten Durchgangs | wenn Server 05 neu gebaut wird |
docs\18-ANTWORT-PANEL-UND-SPRECHANZEIGE.md | Antwort-Panel, Sprecher-Anzeige, Pegel, Doppel-Sprechen | wenn die Oberfläche klemmt |
docs\20-SZENARIEN-BERATERRUNDE.md | Die sechs Szenarien (Aus / Alle / TV-Runde / Pro-Contra / Fazit / Risiko) | vor einer Beraterrunde |
docs\21-NAECHSTER-AUFBAU-PERFORMANCE.md | Speicher und Antwortzeit: was beim nächsten Mal besser wird | vor dem nächsten Aufbau, beim Planen |
docs\22-WER-HOERT-ZU.md | Wer 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.md | Server 09 (Audio/Telefon) neu aufbauen: Playbook, Panel-Weg, fünf Fehler des ersten Laufs | wenn 09 wiederhergestellt wird |
docs\17-WEGWERF-WIEDERAUFBAU-05-ECHT.md | erster echter Durchlauf (90 Minuten, 6 Fallen) | zum Nachlesen, was schon weh tat |
docs\16-SERVER05-EXTERN-NEU-AUSSETZEN.md | Paketbau und Ablauf ohne Panel | wenn das Panel nicht erreichbar ist |
docs\02-mail.md | Mailserver (Postfach-Datenbank, Dovecot, Rspamd) | wenn Mail nicht ankommt |
docs\12-LIVEKIT-LOKAL.md | LiveKit lokal statt Cloud | wenn Gespräche nicht zustande kommen |
docs\04-STEUER127.md, 05-ANLEITUNG-127.md | Steuerserver selbst aufbauen | wenn steuer127 neu muss |
docs\11-SERVER05-LOKAL-BUTTONS.md | der lokale Nachbau auf steuer127 | wenn lokal getestet wird |
docs\13/14/15-… | Wegwerf-Wiederaufbau von Server 01 / 05 / 09 | als 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.
| Playbook | Tut | Hosts | Wichtigste Tags |
|---|---|---|---|
00-server-anlegen.yml | legt einen Wegwerfserver bei Hetzner an (Name muss mit wegwerf- beginnen), hängt die freie Primary IP an | localhost | — |
00b-dns.yml | setzt/entfernt einen A-Eintrag über die Namecheap-API — läuft auf dem Mailserver, weil Namecheap die API nur von dort erlaubt | mail | — (dns_name, dns_ip, dns_sld, dns_tld, dns_modus) |
01b-mailkonto.yml | stellt ein Postfach sicher: Zone + Konto in der vmail-Datenbank, Passwort, Postfachordner, Testmail | mail | — (-e @/root/testzugang.yml) |
05-buttons.yml | der eigentliche Aufbau von Server 05 in neun Phasen | Zielserver | pakete, node, dateien, bauen, python, dienste, webserver, zertifikat, mail, abnahme |
09-audio.yml | Aufbau von Server 09 (Audio/Telefon, xAI realtime) in sieben Phasen | Zielserver | pakete, node, dateien, dienste, webserver, zertifikat, abnahme |
09b-audio-code.yml | Code-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 09 | keine (ein Rutsch) |
08-headscale.yml | Aufbau 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" | Zielserver | pakete, dateien, dienste, webserver, zertifikat, abnahme |
01-livekit.yml | Aufbau von Server 01 (LiveKit + SIP + redis + token-server) aus dem 82-MB-Paket. Stufe 2 (Python-Agenten, Frontend-Build) über -e mit_agenten=true | Zielserver | pakete, dateien, dienste, agenten, webserver, zertifikat, abnahme |
06-gateway.yml | Aufbau von Server 06 (Bastion ins lokale Netz): vier WireGuard-Tunnel, nginx (meet-lokal, livekit-lokal, mcp), Firewall-Regeln. Schalter: mit_tunneln, mit_ufw, ssh_von | Zielserver | pakete, dateien, dienste, ufw, webserver, abnahme |
02-mail.yml | Aufbau 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.yml | Aufbau 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 gelesen | Zielserver | pakete, dateien, dienste, agenten, webserver, zertifikat, abnahme |
|---|---|---|---|
99-wegwerf-loeschen.yml | löscht einen Wegwerfserver über die Hetzner-API | localhost | — |
10-lernschritte.yml | kleine Lernschritte für den Katalog im Panel | Zielserver | verschiedene |
01-steuerserver.yml | baut steuer127 selbst | steuerserver | — |
Wichtige Variablen in 05-buttons.yml:
| Variable | Bedeutung | Vorgabe |
|---|---|---|
domain | Name, unter dem der Server erreichbar ist | muss mitgegeben werden |
namen_suffix | trennt Raumnamen (…541w), damit zwei Server nicht um dieselben Berater-Jobs streiten | leer |
schutz | Passwortschutz der ganzen Seite | automatisch: aus, wenn wegwerf im Namen steht, sonst an |
schutz_admin | Passwortschutz der Verwaltung /meeting-admin | immer an |
berater_last_schwelle | ab welcher Last ein Berater-Worker sich als belegt meldet | 3.0 |
berater_reserve_prozesse | vorgewärmte Prozesse je Berater | 0 (4-GB-Server), auf 8 GB wieder 1 |
protokoll_empfaenger | Standard-Adresse im Feld „Meine E-Mail-Adresse" | leer (dann bleibt der Code-Wert) |
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).
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).
| Was | Wo | Passwort |
|---|---|---|
| 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 Steuerserver | Windows: 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.
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).
/var/lib/steuer-panel/stand.json ({}).Kurzfassung; ausführlich in docs\19-… und docs\17-…:
agents/-Verzeichnis und löschte advisors.json / knowledge-categories.json. Jetzt rsync mit
--exclude und force: false.
203/EXEC), weil das Python-Umfeld fehlte — Schritt 6 braucht bauen,python,dienste zusammen.
wegwerf-buttons statt …unsere-ki-runde.xyz) → neun sinnlose Warteversuche. Jetzt dns_fqdn.
schutz: false. Jetzt aus demNamen abgeleitet; die Verwaltung ist immer geschützt.
/meeting-admin/categories — lag hinter dem Verwaltungs-Passwort. Jetzt
öffentlich (exakter location-Treffer), Verwaltung bleibt zu.
0.95 auf 2-Kern-Server →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.
ssh-keygen -R <IP> vordem Verbindungstest.
var fenster = window; landete 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.
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.
docs\22-WER-HOERT-ZU.md): heutehö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.
docs\21-…): ein Worker für alle Berater statt sechs, 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.
bitte-aendern) und dieTestwerte ersetzen, sobald der Server echt genutzt wird.
04-test gelöscht, weil derServer 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.
/var/www/steuer127/ — Änderungen an 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-….
.env wird eingelesen, nicht ausgeführt: $(…/neu03.env; echo $NAME) 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).
livekit-sip startete nicht ohne libsoxr0, libopus0, libopusfile0 — im Paket sind sie nicht.
Nach dem Einspielen ldd <programm> | grep "not found" prüfen.