StartLobster — Technische Architektur

Übersicht

System-Architektur

Die Plattform besteht aus einem hochverfügbaren Reverse Proxy mit automatischer SSL-Terminierung, Self-Registration der Backend-Server und einer vollautomatisierten Provisioning-Pipeline.

┌─────────────────────────────────────────────────────────────────────┐ │ INTERNET / CLIENTS │ │ │ │ *.startlobster.de → DNS Wildcard A-Record │ └──────────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ FLOATING IP: floating-ip.example │ │ Keepalived VRRP Failover │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ proxy-1 (MASTER) │◄──VRRP──►│ proxy-2 (BACKUP) │ │ │ │ Caddy v2.11 │ sync │ Caddy v2.11 │ │ │ │ SSL Termination │◄──────►│ SSL Termination │ │ │ │ Registration API│ :2019 │ Registration API│ │ │ │ :9876 │ │ :9876 │ │ │ └────────┬─────────┘ └────────┬─────────┘ │ └───────────┼──────────────────────────────┼───────────────────────────┘ │ │ │ Private Network 10.0.0.0/16 │ │ ┌───────────┼──────────────────────────────┼───────────────────────────┐ │ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ s1 (10.0.1.x) │ │ s2 (10.0.1.x) │ │ sN (10.0.1.x) │ ... ×500 │ │ │ │ │ │ │ │ │ │ │ Gateway │ │ Gateway │ │ Gateway │ │ │ │ :18789 │ │ :18789 │ │ :18789 │ │ │ │ Chat UI │ │ Chat UI │ │ Chat UI │ │ │ │ :8888 │ │ :8888 │ │ :8888 │ │ │ │ Auth │ │ Auth │ │ Auth │ │ │ │ :3000 │ │ :3000 │ │ :3000 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ BACKEND SERVER │ └──────────────────────────────────────────────────────────────────────┘

Komponenten

System-Bausteine

Jede Komponente ist unabhängig skalierbar und über klar definierte Schnittstellen verbunden.

🛡️

Reverse Proxy (Caddy)

Zwei Caddy v2.11 Instanzen mit Wildcard SSL-Zertifikat (Let's Encrypt). Automatische SSL-Terminierung für alle *.startlobster.de Subdomains. JSON-basierte Admin API für dynamisches Routing.

🔄

HA Failover (Keepalived)

VRRP-basiertes Failover mit Floating IP. proxy-1 als Master, proxy-2 als Backup. Bei Ausfall automatische IP-Umschaltung via Hetzner API in <5 Sekunden.

📝

Registration API

REST API (Port 9876) auf dem Private Network. Backends registrieren sich selbst beim Proxy. Unterstützt Simple Routes (Gateway) und Full Routes (Auth + UI + Gateway).

🔐

SSL / Zertifikate

Wildcard-Zertifikat via acme.sh mit Custom DNS Hook für http.net API. Automatisches Renewal. Cert-Sync zwischen beiden Proxy-Instanzen.

🌐

DNS (http.net)

Wildcard A-Record *.startlobster.de → Floating IP. Kein individueller DNS-Eintrag pro Server mehr nötig. Verwaltung über http.net Partner API.

⚡

Provisioning Pipeline

Vollautomatisiert: HubSpot-Formular → Hetzner Server → Private Network → Docker + Services → Proxy-Registration. Pool-basiert für Instant-Assignment (<30s).

Infrastruktur

Server & Netzwerk

Komponente	Spezifikation	IP / Netzwerk	Standort
proxy-1 (Master)	CX23 · Debian 12 · Caddy + Keepalived	`proxy-1.example` / `10.0.1.x`	Nürnberg (nbg1)
proxy-2 (Backup)	CX23 · Debian 12 · Caddy + Keepalived	`proxy-2.example` / `10.0.1.y`	Nürnberg (nbg1)
Floating IP	IPv4 · VRRP-gesteuert	`floating-ip.example`	Nürnberg
Private Network	startlobster-net · 10.0.0.0/16	Subnet: `10.0.1.0/24`	eu-central
Backend Server	CX23 · Ubuntu 24.04 · Docker	`10.0.1.x` (Private)	Nürnberg (nbg1)

💡 Netzwerk-Architektur

Backend-Server sind ausschließlich über das Private Network erreichbar. Alle Services (Gateway :18789, Chat UI :8888, Auth :3000) binden nur auf die private IP. Kein öffentlicher Zugang zu Backend-Ports — der gesamte Traffic läuft über den Reverse Proxy.

Routing

Request-Flow

Wie ein Request von einem Client zum richtigen Backend geroutet wird.

DNS Resolution

Client ruft s42.startlobster.de auf → Wildcard DNS löst auf Floating IP floating-ip.example auf.

SSL Termination

Caddy auf dem aktiven Proxy terminiert TLS mit dem Wildcard-Zertifikat *.startlobster.de.

Route Matching

Caddy matched den Host-Header gegen registrierte Routen. Für s42.startlobster.de wird die Full Route verwendet (Auth + Chat UI + Gateway).

Forward Auth

Caddy prüft via forward_auth beim Auth-Container (10.0.1.x:3000), ob der User authentifiziert ist. Bei Erfolg wird der Gateway-Token als Header injiziert.

Reverse Proxy

Je nach Pfad wird zum Backend geroutet:
/auth/* → Auth :3000
/api/* + /ws → Gateway :18789
/* → Chat UI :8888

Self-Registration

Backend Self-Registration API

Neue Server registrieren sich automatisch beim Reverse Proxy — kein manueller DNS-Eintrag oder Config-Änderung nötig.

Endpoint

HTTP
POST http://10.0.1.x:9876/register
Authorization: Bearer <SHARED_SECRET>
Content-Type: application/json

Simple Route (z.B. Gateway-Subdomain)

JSON
{
  "subdomain": "s42-gw",
  "backend_ip": "10.0.1.x",
  "backend_port": 18789,
  "type": "simple"
}

Full Route (Auth + Chat UI + Gateway)

JSON
{
  "subdomain": "s42",
  "backend_ip": "10.0.1.x",
  "type": "full"
}

✅ Auto-Sync

Registrierungen werden automatisch auf beide Proxy-Instanzen synchronisiert. Nur ein API-Call nötig — der empfangende Proxy leitet die Route an den Peer weiter.

Weitere Endpoints

Methode	Pfad	Beschreibung
`POST`	`/register`	Route registrieren (simple oder full)
`POST`	`/deregister`	Route entfernen
`GET`	`/routes`	Alle aktiven Routen auflisten
`GET`	`/health`	Health Check

Provisioning

Automatisierte Server-Bereitstellung

Vom HubSpot-Formular bis zum funktionierenden Server in unter 30 Sekunden dank Server-Pool.

HubSpot Trigger

Neues Formular-Submission → Pipeline erkennt neuen Kunden.

Pool Assignment

Vorkonfigurierter Server aus dem Pool wird zugewiesen. Pool hält 5 ready Server vor. Bei Zuweisung wird automatisch nachprovisioniert.

Hetzner Server + Private Network

CX23 Server wird in startlobster-net erstellt. Erhält automatisch eine private IP (10.0.1.x).

Proxy Registration

Pipeline registriert Full Route + Gateway Route beim Reverse Proxy. Sofort über sXX.startlobster.de erreichbar.

Ansible Provisioning

Playbook install-docker-proxy.yml: Docker, OpenClaw Gateway, Chat UI, Auth — alle Services nur auf Private Network Interface gebunden.

Verification & Notification

Gateway erreichbar? → HubSpot-Note mit Credentials → WhatsApp-Benachrichtigung an Team.

Sicherheit

Security Architecture

🔒

Netzwerk-Isolation

Backend-Services sind nur über Private Network erreichbar. Keine öffentlichen Ports auf Backend-Servern. Gesamter externer Traffic läuft über den Reverse Proxy.

🛡️

Firewall

iptables auf allen Proxies: Port 22/80/443 öffentlich, Admin API (:2019) und Registration API (:9876) nur aus dem Private Network. VRRP-Traffic erlaubt.

🔑

Authentication

Registration API: Bearer Token (Shared Secret). Forward Auth auf dem Proxy für Enduser-Zugang. Gateway Token pro Backend-Instanz. Kein öffentlicher Zugang zu Admin APIs.

⚠️ Sicherheitshinweis

Die Registration API akzeptiert Requests nur aus dem Private Network (10.0.0.0/16). Öffentliche Requests auf Port 9876 und 2019 werden per iptables gedropt bevor sie den Service erreichen.

Backend

Backend Server Stack

Jeder Backend-Server läuft schlank ohne eigenen Reverse Proxy — SSL und Auth werden zentral übernommen.

Container	Port (Private IP)	Funktion
openclaw-gateway	`10.0.1.x:18789`	AI Gateway — WebSocket + REST API
startlobster-chat	`10.0.1.x:8888`	Chat UI (nginx + Static Files)
startlobster-auth	`10.0.1.x:3000`	Auth Container (Token-basiert)

🚀 Vergleich: Legacy vs. Proxy-Modus

Legacy: Jeder Server hatte eigenes Caddy + Let's Encrypt + DNS-Records → 50 Certs/Woche Rate Limit, langsame Provisionierung.
Proxy-Modus: Ein Wildcard-Cert, kein Caddy auf Backends, Instant-Registration. Provisioning ~80% schneller.

Hochverfügbarkeit

Failover-Mechanismus

⚡

Normalzustand

proxy-1 (Master, Priority 101) hält die Floating IP. proxy-2 (Backup, Priority 100) steht bereit. Keepalived prüft alle 5 Sekunden ob Caddy antwortet.

🔴

Master fällt aus

Keepalived auf proxy-2 erkennt fehlende VRRP-Advertisements. Nach 3 fehlgeschlagenen Health Checks (15s) übernimmt proxy-2 die Master-Rolle.

🔄

Floating IP Migration

Keepalived triggert hetzner-failover.sh → Hetzner API reassignt die Floating IP auf proxy-2. DNS bleibt unverändert. Downtime: <15 Sekunden.

✅

Recovery

Wenn proxy-1 wieder online kommt, übernimmt es automatisch die Master-Rolle zurück (höhere Priority). Floating IP migriert zurück.

Tech Stack

Eingesetzte Technologien

Kategorie	Technologie	Version / Details
Reverse Proxy	Caddy	v2.11.1 (Custom Build via xcaddy)
HA / Failover	Keepalived	VRRP auf Private Network Interface
SSL Certificates	Let's Encrypt + acme.sh	Custom DNS Hook für http.net API
DNS	http.net Partner API	Wildcard A-Record
Cloud	Hetzner Cloud	CX23, Debian 12 / Ubuntu 24.04
Networking	Hetzner Private Network	10.0.0.0/16, Floating IP
Container Runtime	Docker + Compose	Latest stable
Provisioning	Ansible + Python Pipeline	Idempotent, Pool-basiert
Registration API	Python (stdlib)	http.server, Port 9876
CRM Integration	HubSpot API	Form Submissions + Contact Notes
Notifications	WhatsApp (OpenClaw)	Auto-Notify bei Provisioning

StartLobster Architektur

Reverse Proxy (Caddy)

HA Failover (Keepalived)

Registration API

SSL / Zertifikate

DNS (http.net)

Provisioning Pipeline

DNS Resolution

SSL Termination

Route Matching

Forward Auth

Reverse Proxy

Endpoint

Simple Route (z.B. Gateway-Subdomain)

Full Route (Auth + Chat UI + Gateway)

Weitere Endpoints

HubSpot Trigger

Pool Assignment

Hetzner Server + Private Network

Proxy Registration

Ansible Provisioning

Verification & Notification

Netzwerk-Isolation

Firewall

Authentication

Normalzustand

Master fällt aus

Floating IP Migration

Recovery