Uncloud

Uncloud-Cluster-Management

Referenz für die uc CLI – eine dezentrale Self-Hosting-Plattform, die Docker-Container, WireGuard-Mesh-Netzwerke und den Caddy-Reverse-Proxy nutzt.

Wann aktivieren

Verwenden Sie dieses Skill bei der Arbeit mit Uncloud-Clustern, insbesondere wenn:

• Maschinen mit uc machine initialisiert oder dem Cluster hinzugefügt werden
• Dienste aus Compose-Dateien mit uc deploy bereitgestellt werden
• HTTP-, HTTPS-, TCP- oder UDP-Ports über Uncloud veröffentlicht werden
• Der Caddy-Ingress mit x-caddy, x-ports oder --caddyfile konfiguriert wird
• Externe LAN-Geräte über den Cluster-Proxy geroutet werden
• Logs, Service-Zustände, Volumes, DNS oder die Maschinenplatzierung inspiziert werden

Funktionsweise

Uncloud betreibt Docker-Dienste auf mehreren Maschinen, die über ein WireGuard-Mesh verbunden sind. Jede Maschine ist ein gleichberechtigtes Cluster-Mitglied; Dienste kommunizieren über das Overlay-Netzwerk und Caddy wird global ausgeführt, um öffentlichen HTTP/HTTPS-Traffic zu terminieren. Compose-Dateien können Uncloud-Erweiterungen für Ingress, Platzierung und generierte Caddy-Konfigurationen nutzen, während die uc CLI die Image-Verteilung, Planung, Skalierung, Logs und den Cluster-Zustand verwaltet.

Beispiele

uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy

Kernkonzepte

• Kein zentraler Control-Plane – alle Maschinen sind gleichberechtigte Peers, die über WireGuard verbunden sind
• Caddy läuft als globaler Dienst auf jeder Maschine; bezieht automatisch TLS-Zertifikate von Let's Encrypt
• Overlay-Netzwerk – Dienste kommunizieren standardmäßig über 10.210.0.0/16; DNS wird innerhalb des Meshes bereitgestellt
• Caddyfile wird automatisch generiert – niemals direkt bearbeiten; stattdessen x-caddy / --caddyfile verwenden

---

Kurzreferenz der CLI

Maschinen

Befehl	Zweck
uc machine init user@host	Erste Maschine / neues Cluster bootstrappen
uc machine add user@host	Maschine zu bestehendem Cluster hinzufügen
uc machine ls	Maschinen auflisten
uc machine update NAME --public-ip IP	Öffentliche IP für Ingress aktualisieren
uc machine rm NAME	Maschine entfernen

Wichtige init-Flags: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none

Dienste

Befehl	Zweck
uc service ls / uc ls	Dienste auflisten
uc service run IMAGE	Einen einzelnen Container-Dienst ausführen
uc deploy	Aus compose.yaml bereitstellen
uc deploy --no-build	Bereits gepushte Images ohne Neuerstellung bereitstellen
uc deploy --recreate	Dienstneuerstellung erzwingen
uc scale SERVICE N	Replikatanzahl festlegen
uc service logs SERVICE	Logs anzeigen
uc service exec SERVICE	Shell im Container öffnen
uc service inspect SERVICE	Detaillierte Informationen
uc service rm SERVICE	Dienst entfernen (behält benannte Volumes)
uc ps	Alle Container im Cluster

Images

uc image push myapp:latest                    # Lokales Image auf alle Maschinen pushen
uc image push myapp:latest -m machine1,machine2  # Auf bestimmte Maschinen pushen
uc images                                     # Images im Cluster auflisten

Volumes

uc volume ls                  # Alle Volumes
uc volume ls -m machine1      # Auf bestimmter Maschine
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

uc caddy config    # Aktuelles generiertes Caddyfile anzeigen (schreibgeschützt)
uc caddy deploy    # Caddy clusterweit bereitstellen / aktualisieren

DNS & Kontext

uc dns show        # Reservierte *.uncld.dev-Domain anzeigen
uc dns reserve     # Neue Domain reservieren
uc ctx ls          # Cluster-Kontexte auflisten
uc ctx use prod    # Kontext wechseln

---

Port-Veröffentlichung

HTTP/HTTPS (über Caddy-Reverse-Proxy)

-p [hostname:]container_port[/protocol]

Beispiel	Bedeutung
-p 8080/https	HTTPS mit automatischem dienstname.cluster-domain-Hostnamen
-p app.example.com:8080/https	HTTPS mit benutzerdefiniertem Hostnamen
-p 8080/http	Nur HTTP, ohne TLS

TCP/UDP (hostgebunden, umgeht Caddy)

-p [host_ip:]host_port:container_port[/protocol]@host

Beispiel	Bedeutung
-p 5432:5432@host	TCP 5432 auf allen Schnittstellen
-p 127.0.0.1:5432:5432@host	TCP 5432 nur Loopback
-p 53:5353/udp@host	UDP

---

Compose-Datei-Erweiterungen

Uncloud fügt diese Erweiterungen zu Docker Compose hinzu:

x-ports – Ports mit Domains veröffentlichen

services:
  app:
    image: app:latest
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
      - api.example.com:9000/https

x-caddy – Benutzerdefinierte Caddy-Konfiguration für den Dienst

services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }

Verfügbare Template-Funktionen innerhalb von x-caddy:

• {{upstreams [service] [port]}} – IPs gesunder Container
• {{.Name}} – Dienstname
• {{.Upstreams}} – Map aller Dienste zu IPs

x-machines – Platzierungsbeschränkungen

services:
  db:
    image: postgres:18
    x-machines: db-machine          # Einzelner Maschinenname
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

Vollständiges Mehr-Dienst-Beispiel

services:
  api:
    build: ./api
    x-ports:
      - api.example.com:3000/https
    environment:
      DATABASE_URL: postgres://db:5432/mydb

  web:
    build: ./web
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
    environment:
      API_URL: http://api:3000

  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    x-machines: db-machine

volumes:
  db-data:

---

Routing zu externen (Nicht-Cluster-)Geräten

Um ein externes Gerät (z.B. BMC, NAS, Router-UI) über Caddy verfügbar zu machen, ohne einen echten Container zu betreiben:

1. Caddyfile-Snippet erstellen (z.B. ~/device.caddyfile):

https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # notwendig für selbstsignierte BMC-Zertifikate
        }
    }
    log
}

Für unverschlüsselten Upstream: reverse_proxy http://192.168.1.x:port

2. Als benannten Dienst mit Noop-Container registrieren:

uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9

pause ist ein minimaler Noop-Container – er tut nichts, gibt Uncloud aber einen Service-Eintrag, an den das Caddyfile angehängt werden kann.

3. Überprüfen:

uc caddy config   # Der Block für device.example.com sollte erscheinen

--caddyfile kann nicht zusammen mit nicht-@host veröffentlichten Ports verwendet werden.

DNS-Tipp: Ein Wildcard-Eintrag (*.yourdomain.com → cluster-public-ip) bewirkt, dass jede neue Subdomain sofort funktioniert – kein DNS-Wechsel pro Dienst erforderlich.

---

Dienst-DNS (Intern)

Dienste im Cluster lösen sich gegenseitig über ihren Namen auf:

DNS-Name	Löst auf zu
service-name	Jeder gesunde Container
service-name.internal	Gleich wie oben
rr.service-name.internal	Round-Robin
nearest.service-name.internal	Zuerst maschinenlokal

---

Skalierung & Globale Dienste

uc scale web 5    # 5 Replikate (verteilt auf Maschinen)
uc scale web 1    # Herunterskalieren

services:
  caddy:
    deploy:
      mode: global   # Ein Container auf jeder Maschine

---

Image-Tag-Templates (in compose.yaml)

image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

Funktion	Ausgabe
{{gitsha N}}	Erste N Zeichen des Commit-SHA
{{gitdate "format"}}	Git-Commit-Datum im Go-Format
{{date "format"}}	Aktuelles Datum

---

Häufige Workflows

Aus dem Quellcode bereitstellen:

uc deploy                          # Bauen + Pushen + Bereitstellen
uc build --push && uc deploy --no-build   # Getrennte Schritte

Einen Dienst inspizieren:

uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # Shell öffnen
uc exec web /bin/sh -c "env"       # Spezifischen Befehl ausführen

Zero-Downtime-Deployments erfolgen automatisch; Uncloud wartet auf Health-Checks, bevor alte Container terminiert werden.

Neuerstellung erzwingen:

uc deploy --recreate

---

Häufige Fehler

Fehler	Lösung
Das Caddyfile direkt bearbeiten	x-caddy in compose oder --caddyfile bei uc service run verwenden
HTTPS-Upstream mit selbstsigniertem Zertifikat proxen	transport http { tls_insecure_skip_verify } hinzufügen
uc caddy config zeigt keine benutzerdefinierten Blöcke	Caddy-Admin-Socket nicht erreichbar – uc inspect caddy und uc logs caddy prüfen
Dienst kann externes LAN-IP aus Container nicht erreichen	Sicherstellen, dass der Host des Caddy-Containers eine Route zum Zielnetzwerk hat
Volumes nach uc service rm verloren	Benannte Volumes bleiben erhalten; nur anonyme Volumes werden automatisch entfernt