Konfigurationsreferenz

Wippy liest seine Runtime-Konfiguration aus .wippy.yaml-Dateien.

Verwenden Sie die wiederholbare Option wippy run --set section.path=value, um die folgenden Konfigurationsfelder beim Start zu überschreiben. Für einzelne Registry-Einträge statt Konfigurationsabschnitte verwenden Sie override: oder -o; siehe Einträge überschreiben.

Konfigurations-Komposition {#config-composition}

--config ist wiederholbar; Dateien komponieren von links nach rechts mit demselben Schema:

wippy run --config .wippy.yaml --config .wippy.local.yaml

• Spätere Dateien überschreiben übereinstimmende Werte und behalten alles andere bei.
• Jede explizit benannte Datei muss existieren. Ohne --config ist die Standarddatei .wippy.yaml optional.
• Die erste Datei verankert das Verzeichnis, gegen das relative Pfade aufgelöst werden.
• Dateinamen tragen keine reservierte Bedeutung; nichts außer dem Standard wird automatisch entdeckt.

Die Konfiguration wird in dieser Reihenfolge angewendet: komponierte Dateien, ausgewählte --profile-Overlays und anschließend --set-Überschreibungen. Bei Anwendungen aus Packs haben gepackte Runtime-Defaults eine niedrigere Priorität; siehe Runtime-Defaults veröffentlichen.

Profile {#profiles}

Eine Konfigurationsdatei kann benannte Overlays unter profiles: deklarieren. Jeder Profilkörper spiegelt die normalen Konfigurationsabschnitte; die Auswahl mit --profile <name> legt diese Werte über die zusammengeführte Basiskonfiguration:

version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]

wippy run --profile pg

• --profile ist wiederholbar; Profile komponieren von links nach rechts, nach der Datei-Komposition und vor --set. Ein unbekannter Name ist ein Fehler.
• Werte werden pro Blatt zusammengeführt (der letzte Schreiber gewinnt). Der Abschnitt profiles: selbst wird aus der aufgelösten Konfiguration entfernt.
• Der Abschnitt disable unterstützt Listenoperationen innerhalb von Profilen — namespaces.add, namespaces.remove, entries.add, entries.remove — sodass ein Profil die Basisliste anpassen kann, statt sie zu ersetzen.
• ${name}-Referenzen interpolieren aus dem zusammengeführten vars:-Abschnitt. OS-Umgebungsreferenzen sind innerhalb von Profil-Vars nicht erlaubt; verwenden Sie ${env:NAME} in der Basiskonfiguration, aufgelöst beim Laden der Datei.

wippy run, test und pack akzeptieren --profile; run list, install, update, lint und registry akzeptieren es ebenfalls für Workspace-Profile (zusammen mit --set). Anwendungen können Profile in Packs ausliefern — siehe Profile veröffentlichen.

Logger

Steuert den zap-Logger-Encoder. CLI-Flags (-v, -c, -s) überschreiben Level/Ausgabe; die einzige yaml-gesteuerte Option ist die Kodierung.

logger:
  encoding: json

Log-Manager

Steuert das Runtime-Log-Routing. Konsolenausgabe wird über CLI-Flags (-v, -c, -s) konfiguriert.

logmanager:
  propagate_downstream: true
  stream_to_events: false

Siehe: Logger-Modul

Profiler

Go pprof HTTP-Server für CPU-/Speicher-Profiling. Mit -p Flag oder Konfiguration aktivieren.

profiler:
  enabled: true
  address: "localhost:6060"

Zugriff unter http://localhost:6060/debug/pprof/

Sicherheit

Globales Sicherheitsverhalten. Individuelle Richtlinien werden als security.policy-Einträge definiert.

security:
  strict_mode: false

Siehe: Sicherheitssystem, Sicherheitsmodul

Registry

Eintragsspeicherung und Versionshistorie. Die Registry enthält alle Konfigurationseinträge.

registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db

registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry

Siehe: Registry-Konzept, Registry-Modul

Artifact

Ausgabewurzel für materialisierte Build-Zeit-Artefakte.

artifact:
  materialization_root: build/wippy

Siehe: Build-Zeit-Artefakte

Workspace

Lokale Modulersetzungen, adressiert über org/module. Die Werte sind Verzeichnisse; relative Pfade werden gegen das Verzeichnis der ersten --config-Datei aufgelöst, und null deaktiviert eine Ersetzung, die aus einer früheren Konfigurationsebene oder einem Profil geerbt wurde.

workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null

Ersetzungen werden nie in wippy.lock geschrieben. Siehe Lokale Entwicklung mit Ersetzungen.

Relay

Nachrichtenrouting zwischen Prozessen über Knoten hinweg.

relay:
  node_name: worker-1

Siehe: Prozessmodell

Supervisor

Dienst-Lebenszyklus-Verwaltung. Steuert das interne Steuerungs-Postfach des Supervisors, das zum Versand von Lebenszyklus-Ereignissen verwendet wird.

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

Siehe: Supervision-Anleitung

Lua-Runtime

Lua-VM-Caching und Expression-Auswertung.

lua:
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

Siehe: Lua-Übersicht

Scheduler

Core-Partitionierung für die WASM-Runtime. Wenn aktiviert, werden reserved_cores CPUs für die WASM-Ausführung reserviert und die übrigen bedienen den Actor-Scheduler; eine ungültige Aufteilung (zum Beispiel mehr reservierte Cores als verfügbar) wird protokolliert und ignoriert.

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

Finder

Registry-Such-Caching. Wird intern für Eintrags-Lookups verwendet.

finder:
  query_cache_size: 2000

OpenTelemetry

Verteiltes Tracing und Metrik-Export über OTLP.

otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true

Standard-OTEL-Umgebungsvariablen (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_INSECURE, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS) überschreiben die entsprechenden Felder.

Siehe: Observability-Anleitung

Herunterfahren :id=shutdown

Verhalten beim kontrollierten Herunterfahren.

shutdown:
  timeout: 60s

Metriken

Interner Metriken-Sammlungspuffer.

metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true

Siehe: Metriken-Modul, Observability-Anleitung

Prometheus

Prometheus-Metriken-Endpunkt.

prometheus:
  enabled: true
  address: "0.0.0.0:9090"

Stellt /metrics-Endpunkt für Prometheus-Scraping bereit, zusätzlich /livez.

Siehe: Observability-Anleitung

Cluster

Multi-Node-Clustering: Gossip-Mitgliedschaft plus ein begrenzter Raft-Konsenskern. Siehe den Cluster-Leitfaden für Architektur und Betriebsmodell; dieser Abschnitt ist die Konfigurationsschlüssel-Referenz.

Oberste Ebene

Mitgliedschaft (Gossip)

SWIM-Gossip über memberlist. Wird für Knotenentdeckung, Fehlererkennung und Metadaten-Verbreitung verwendet.

Ein Gossip-Secret ist erforderlich. Entweder membership.secret_key oder membership.secret_file setzen (die Datei gewinnt, wenn beides angegeben ist); ohne beides startet die Cluster-Komponente nicht. Der Wert ist base64-kodiert.

Die vier Probe-Schlüssel erben die Local-Network-Defaults von memberlist, wenn sie nicht gesetzt sind; erhöhen Sie sie für Verbindungen mit hoher Latenz (z.B. probe_interval: 2s, probe_timeout: 500ms, suspicion_mult: 5).

Internode (Transport)

TCP-Mesh für Relay- und Raft-Verkehr zwischen Knoten. Raft nutzt dieses Mesh über Internode-Request/Reply; es gibt keinen separaten Raft-Port.

advertise_addr/advertise_port veröffentlichen einen additiven Endpunkt in den Knoten-Metadaten, während der Bind-Endpunkt unverändert beworben bleibt, sodass Cluster mit gemischten Versionen während eines Rolling Upgrades verbunden bleiben.

Die Internode-Identität ist zwingend, sobald Clustering aktiviert ist. identity_key und identity_key_file schließen sich gegenseitig aus, und eines von beiden muss vorhanden sein; der Wert dekodiert (Standard- oder Raw-base64) entweder zu einem 32-Byte-ed25519-Seed oder zu einem 64-Byte-ed25519-Privatschlüssel. trusted_peer_keys bildet jeden Knotennamen auf den 32-Byte-ed25519-Public-Key dieses Knotens ab und muss einen Eintrag für den lokalen cluster.name enthalten, dessen Wert zur lokalen Identität passt — andernfalls schlägt der Start fehl. Siehe die Cluster-Anleitung.

Raft (Konsens)

Begrenztes Raft. Der Raft-Zustand ist standardmäßig fs-dauerhaft und wird unter raft.data_dir (Standard ~/.wippy/store) gespeichert; ein neugestarteter Knoten tritt dem Quorum dennoch von Peers wieder bei. store.kv.raft-Einträge replizieren darüber. Bootstrap ist gossip-gesteuert (Consul/Nomad bootstrap_expect-Stil).

Einzelknoten (Entwicklung) — Clustering aktiviert, bootstrappt sich sofort:

cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1

Drei-Knoten-Voting-Cluster — jeder Knoten listet die anderen als Seeds und wartet auf alle drei vor der Quorumbildung. Jeder Knoten trägt dieselbe trusted_peer_keys-Karte und seinen eigenen privaten Schlüssel:

cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5

Gossip-only-Client — tritt dem Cluster für Benennung/Messaging bei, betreibt nie Raft. Er braucht dennoch eine eigene Identität und muss in der Vertrauenskarte jedes Knotens auftauchen:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client

LSP

Language-Server-Protocol-Server für Editor-Integrationen.

lsp:
  enabled: true
  address: ":7777"
  http_enabled: true

Siehe: LSP-Anleitung

Netzwerkdienst

Overlay-Netzwerk-Manager (SOCKS5-, I2P-, Tailscale-Treiber).

network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale

Siehe: Netzwerk-Overlays

HTTP-Dispatcher

Tuning für den gemeinsamen HTTP-Client-Pool, der von HTTP-dispatched Funktionen und ausgehenden Anfragen verwendet wird.

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Module

Modul-Registry-Client, der von wippy install/update verwendet wird.

modules:
  registry_url: https://internal-registry.example.com

Erweiterungen

Native Go-Plugin-Erweiterungen, die beim Booten geladen werden (nur Unix).

extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so

Umgebungsvariablen

Internode-TLS

Aktivieren Sie gegenseitiges TLS für das Internode-TCP-Mesh mit cluster.internode.tls. Damit wird auch der darüber transportierte Relay- und Raft-Verkehr geschützt. Ergänzen Sie die bestehende Cluster-Konfiguration:

cluster:
  internode:
    tls:
      enabled: true
      cert_file: /etc/wippy/node.crt
      key_file: /etc/wippy/node.key
      ca_file: /etc/wippy/cluster-ca.pem

TLS ist standardmäßig deaktiviert. Bei enabled: true sind alle drei nicht leeren Dateipfade erforderlich: ein PEM-Zertifikat, der passende private Schlüssel und ein PEM-CA-Bundle zur Prüfung von Server- und Client-Zertifikaten. Die Mindestversion ist TLS 1.2. Alle Peers benötigen kompatible Zertifikate und Vertrauenswurzeln. Die ed25519-Identität und die Liste vertrauenswürdiger Peer-Schlüssel bleiben erforderlich.

Unbekannte TLS-Einstellungen, ungültige Typen, fehlende oder ungültige Zugangsdaten, fehlerhafte CA-Bundles und Dateipfade ohne enabled: true verhindern den Start. Eine ungültige explizite Konfiguration fällt niemals stillschweigend auf Klartext zurück.

Siehe auch

• CLI-Referenz — Kommandozeilenoptionen
• Cluster-Leitfaden — Clustering-Architektur und Betrieb
• Entry-Kinds — Entry-Kinds und Felder
• Observability — Logging, Metriken und Tracing