GUIDE · ANLEITUNG

HYPDB.ONE mit CasaOS verbinden

Docker-Container, Port-Konfiguration und nginx-Reverse-Proxy — in 15 Minuten einsatzbereit

Überblick

CasaOS ist die ideale Plattform, um HYPDB.ONE auf dem eigenen Homeserver zu betreiben. Mit CasaOS als Docker-Host und HYPDB.ONE als KI-Dashboard entsteht ein leistungsfähiges, lokales KI-System, das vollständig unter deiner Kontrolle bleibt.

Diese Anleitung zeigt dir Schritt für Schritt, wie du HYPDB.ONE in einem CasaOS-Docker-Container installierst, die Port-Konfiguration vornimmst und einen nginx-Reverse-Proxy für den öffentlichen Zugriff einrichtest.

Voraussetzungen: CasaOS auf einem Linux-Server (Debian/Ubuntu), Docker installiert, grundlegende SSH-Kenntnisse.

Schritt-für-Schritt-Anleitung

1

CasaOS vorbereiten

Stelle sicher, dass CasaOS läuft und Docker-Container ausführen kann. Öffne die CasaOS-Web-Oberfläche und prüfe unter Einstellungen → Speicher, ob ausreichend Speicherplatz vorhanden ist.

# CasaOS-Status prüfen (via SSH auf dem Server): systemctl status casaos # Erwartet: active (running) # Docker-Status prüfen: docker info | head -5 # Erwartet: Server Version: 24.x.x
2

HYPDB.ONE Docker-Image pullen

WICHTIG — Stand dieser Anleitung: Ein offiziell im Docker Hub oder auf Docker.io unter hypdb/hypdb-one veröffentlichtes Image ist derzeit nicht nachweisbar. Diese Anleitung beschreibt daher das Projekt-Setup in eigener Registry: Du baust das Image selbst aus dem Quellcode-Paket und lädst es in deine Registry, oder du importierst ein bereits gebautes Image, das dir mit dem Kauf bereitgestellt wurde. Ersetze in allen folgenden Befehlen HYPDB-REGISTRY/ durch deinen tatsächlichen Registry-Pfad. Wirft docker pull den Fehler repository not found, ist genau das die Ursache — nicht deine Docker-Installation.

Das Image enthält nginx (Frontend), das Python/FastAPI-Backend und alle statischen Assets. Bauen statt ziehen, wenn du den Quellcode hast:

# Variante A: eigenes Image bauen und lokal taggen docker build -t hypdb-one:local . docker tag hypdb-one:local HYPDB-REGISTRY/hypdb-one:latest # Variante B: in eine eigene Registry hochladen docker push HYPDB-REGISTRY/hypdb-one:latest # Variante C: Image aus einem Tar-Archiv laden docker load -i hypdb-one.tar docker images | grep hypdb
TIPP: Verwende nie latest produktiv. Tagge eine konkrete Version (z. B. v3.0.0), damit ein Rollback auf eine bekannte Konfiguration möglich ist.
3

Container starten mit Port-Mapping

Starte den Container mit dem korrekten Port-Mapping. HYPDB.ONE verwendet intern Port 80 (nginx), der auf dem Host auf Port 8080 gemappt wird. Port 80 auf dem Host bleibt für CasaOS frei.

docker run -d \ --name hypdb-one \ -p 8080:80 \ -p 7777:7777 \ --restart unless-stopped \ HYPDB-REGISTRY/hypdb-one:latest

Port-Erklärung:

  • 8080 → 80: nginx-Webserver (HYPDB.ONE-Frontend)
  • 7777 → 7777: Python/FastAPI-Backend (API-Endpunkte)
WICHTIG: CasaOS verwendet Port 80 auf dem Host. Mappe HYPDB.ONE daher auf Port 8080, um Konflikte zu vermeiden. Der Zugriff erfolgt dann über http://dein-server:8080.
4

nginx-Reverse-Proxy konfigurieren

Für den öffentlichen Zugriff über eine Domain (z.B. hypdb.one) richtest du einen nginx-Reverse-Proxy ein. Dieser leitet Anfragen von Port 80/443 an den Docker-Container auf Port 8080 weiter.

# nginx-Konfiguration für HYPDB.ONE # Datei: /etc/nginx/sites-available/hypdb.one server { listen 80; server_name hypdb.one www.hypdb.one; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name hypdb.one www.hypdb.one; ssl_certificate /etc/letsencrypt/live/DEINE-DOMAIN/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/DEINE-DOMAIN/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /api/ { proxy_pass http://127.0.0.1:7777; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }
TIPP: Verwende Certbot (Let's Encrypt) für automatische SSL-Zertifikate. Installiere es mit apt install certbot python3-certbot-nginx und führe certbot --nginx -d hypdb.one -d www.hypdb.one aus.
5

Cloudflare-Tunnel (optional)

Alternativ zum Reverse-Proxy kannst du einen Cloudflare-Tunnel verwenden. Das ist besonders nützlich, wenn du keinen öffentlichen Port freigeben möchtest oder hinter einem NAT-Router sitzt.

# Cloudflared installieren: curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared chmod +x /usr/local/bin/cloudflared # Tunnel authentifizieren: cloudflared tunnel login # Tunnel erstellen und konfigurieren: cloudflared tunnel create hypdb-tunnel cloudflared tunnel route dns hypdb-tunnel hypdb.one # Config: ~/.cloudflared/config.yml # tunnel: hypdb-tunnel # credentials-file: …/.cloudflared/hypdb-tunnel.json # ingress: # - hostname: hypdb.one # service: http://localhost:8080 # - hostname: www.hypdb.one # service: http://localhost:8080 # - service: http_status:404
WICHTIG: Der Cloudflare-Tunnel muss auf den korrekten Host-Port zeigen. Bei HYPDB.ONE ist das Port 8080 (nicht Port 80!). Ein häufiger Fehler ist die Konfiguration auf Port 8765 (MCP/FastAPI) statt 8080 (nginx).
6

Verifikation

Prüfe nach der Einrichtung, ob alles korrekt funktioniert. Diese Endpunkte antworten auf einer laufenden HYPDB.ONE-Instanz und eignen sich als echter Funktionstest — ein HTTP-200 auf die Startseite allein beweist nur, dass nginx etwas ausliefert:

# 1. Container läuft? docker ps | grep hypdb # 2. Lokaler Zugriff (vom Server aus): curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/ # Erwartet: 200 # 3. Frontend wird wirklich ausgeliefert (nicht nur ein Fallback): curl -s http://127.0.0.1:8080/ | grep -i "<title>" # Erwartet: eine HTML-Seite mit <title>… # 4. Auth-Dienst läuft? (liefert JSON, keinen HTML-Fallback) curl -s http://127.0.0.1:7777/health # Erwartet: {"status": "ok", "service": "hypdb-auth"} # ACHTUNG: Eine Antwort mit "text/html" ist KEIN Backend, sondern der nginx-Fallback. # 5. Aktuelle Tarifdaten kommen aus der Datenbank? curl -s http://127.0.0.1:7777/api/tiers # Erwartet: JSON mit "tiers": [ … ] und vier Eintraegen # (starter / pro / business / enterprise) # 6. Zugriffsschutz wirkt? /api/me muss ohne Token ablehnen: curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7777/api/me # Erwartet: 401 — ein 200 hier waere ein offener Zugang, kein Erfolg. # 7. Öffentlicher Zugriff (von extern): curl -s -o /dev/null -w "%{http_code}" https://www.hypdb.one/ # Erwartet: 200
MERKE: Prüfe bei jedem Request das Content-Type-Feld, nicht nur den Statuscode. nginx beantwortet auch einen unbekannten Pfad mit HTTP 200 und einer HTML-Startseite. Diese Antwort sieht Erfolg aus, ist aber eine Sackgasse — genau daran scheitern die meisten "läuft doch"-Diagnosen.

Häufige Fehler und Lösungen

Passende Guides als nächster Schritt

Diese Anleitung deckt die Basis-Installation ab. Für den Betrieb danach:

Plattformstatus (live)

Die folgenden Werte werden direkt von der laufenden Instanz gemessen, nicht aus einer Textvorlage. Sie zeigen den Zustand des Referenzsystems, auf dem diese Anleitung beschrieben wurde — nicht deine eigene Installation, solange du sie noch nicht aufgebaut hast.

PRÜFE… Plattformstatus wird geladen…

Nächste Schritte

Nach erfolgreicher Installation kannst du: