設定リファレンス

Wippy は .wippy.yaml ファイルからランタイム設定を読み取ります。

以下の設定フィールドは、繰り返し指定できる wippy run --set section.path=value オプションを使用して起動時に上書きできます。これらの設定セクションではなく個々のレジストリエントリを上書きするには、override: セクションまたは -o を使用します。エントリの上書きを参照してください。

設定の合成 {#config-composition}

--config は繰り返し指定でき、同じスキーマを用いてファイルを左から右に合成します：

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

• 後のファイルは一致する値を上書きし、それ以外はすべて保持します。
• 明示的に指定したファイルはすべて存在しなければなりません。--config なしの場合、デフォルトの .wippy.yaml は任意です。
• 最初のファイルが、相対パスの解決に使われるディレクトリを決めます。
• ファイル名に予約された意味はありません。デフォルト以外は何も自動探索されません。

設定は、合成されたファイル、選択された --profile オーバーレイ、--set の上書きの順に適用されます。パックから実行されるアプリケーションでは、パックされたランタイムデフォルトの優先順位はこれら 3 つより低くなります。ランタイムデフォルトの公開を参照してください。

プロファイル {#profiles}

設定ファイルは profiles: の下に名前付きオーバーレイを宣言できます。各プロファイルの本体は通常の設定セクションと同じ構造で、--profile <name> で選択すると、マージされたベース設定にその値がオーバーレイされます：

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 は繰り返し指定できます。プロファイルはファイル合成の後、--set の前に左から右へ合成されます。未知の名前はエラーです。
• 値はリーフ単位でマージされます（最後の書き込みが優先）。profiles: セクション自体は解決後の設定から取り除かれます。
• disable セクションはプロファイル内でのリスト操作をサポートします — namespaces.add、namespaces.remove、entries.add、entries.remove — これにより、プロファイルはベースのリストを置き換えるのではなく調整できます。
• ${name} 参照はマージ後の vars: セクションから補間されます。プロファイルの vars 内で OS 環境変数を参照することはできません。ベース設定で ${env:NAME} を使用してください。これはファイルのロード時に解決されます。

wippy run、test、pack は --profile を受け付けます。run list、install、update、lint、registry もワークスペースプロファイル用にこれを受け付けます（--set と併せて）。アプリケーションはプロファイルをパック内に同梱できます — プロファイルの公開を参照してください。

Logger

zap ロガーのエンコーダを制御します。CLI フラグ（-v, -c, -s）はレベル/出力を上書きします。yaml で制御できる唯一のオプションはエンコーディングです。

logger:
  encoding: json

ログマネージャ

ランタイムログルーティングを制御します。コンソール出力は CLI フラグ（-v, -c, -s）で設定します。

logmanager:
  propagate_downstream: true
  stream_to_events: false

参照: ロガーモジュール

プロファイラ

CPU/メモリプロファイリング用のGo pprof HTTPサーバー。-pフラグまたは設定で有効化。

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

デフォルトのアドレスで有効にすると、プロファイラは http://localhost:6060/debug/pprof/ で利用できます。

セキュリティ

グローバルなセキュリティ動作です。個別のポリシーは security.policy エントリとして定義されます。

security:
  strict_mode: false

参照: セキュリティシステム, セキュリティモジュール

レジストリ {#registry}

エントリストレージとバージョン履歴。レジストリはすべての設定エントリを保持します。

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

参照: レジストリコンセプト, レジストリモジュール

アーティファクト

実体化されたビルド時アーティファクトの出力ルート。

artifact:
  materialization_root: build/wippy

参照: ビルド時アーティファクト

ワークスペース

org/module をキーとするローカルモジュールの置き換え。値はディレクトリで、相対パスは最初の --config ファイルのディレクトリを基準に解決されます。null は、以前の設定レイヤーやプロファイルから継承した置き換えを無効化します。

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

置き換えが wippy.lock に書き込まれることはありません。置き換えによるローカル開発を参照してください。

リレー

ノード間のプロセス間メッセージルーティング。

relay:
  node_name: worker-1

参照: プロセスモデル

スーパーバイザ

サービスライフサイクル管理。ライフサイクルイベントのディスパッチに使用されるスーパーバイザの内部制御メールボックスを制御します。

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

参照: スーパービジョンガイド

Luaランタイム

Lua VMキャッシュと式評価。

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

参照: Lua概要

スケジューラ

WASM ランタイム向けのコア分割。有効にすると reserved_cores 個の CPU が WASM 実行のために確保され、残りがアクターのスケジューラに割り当てられます。不正な分割（たとえば利用可能な数より多いコアの予約）はログに記録され、無視されます。

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

ファインダー

レジストリ検索キャッシュ。エントリルックアップに内部的に使用されます。

finder:
  query_cache_size: 2000

OpenTelemetry

OTLPによる分散トレーシングとメトリクスエクスポート。

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

標準 OTEL 環境変数（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）は一致するフィールドを上書きします。

参照: 可観測性ガイド

シャットダウン

グレースフルシャットダウン動作。

shutdown:
  timeout: 60s

メトリクス

内部メトリクス収集バッファ。

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

参照: メトリクスモジュール, 可観測性ガイド

Prometheus

Prometheusメトリクスエンドポイント。

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

Prometheusスクレイピング用の/metricsエンドポイントに加え、/livezを公開します。

参照: 可観測性ガイド

クラスタ {#cluster}

マルチノードクラスタリング: ゴシップメンバーシップと有界 Raft コンセンサスコア。アーキテクチャと運用モデルについてはクラスタガイドを参照してください。このセクションは設定キーのリファレンスです。

トップレベル

メンバーシップ（ゴシップ）

memberlist による SWIM ゴシップ。ノード探索、障害検出、メタデータ伝播に使用されます。

ゴシップシークレットは必須です。membership.secret_key または membership.secret_file を設定してください（両方を指定した場合はファイルが優先されます）。どちらも指定しないと、クラスタコンポーネントは起動に失敗します。値は base64 エンコードされます。

4つのプローブキーは、未設定の場合 memberlist のローカルネットワーク向けデフォルトを継承します。レイテンシの高いリンクでは値を引き上げてください（例: probe_interval: 2s、probe_timeout: 500ms、suspicion_mult: 5）。

ノード間（トランスポート）

ノード間でリレーと Raft トラフィックを運ぶ TCP メッシュ。Raft はノード間のリクエスト/リプライを介してこのメッシュ上を走行し、独立した Raft ポートはありません。

advertise_addr/advertise_port はノードメタデータに追加のエンドポイントを公開し、バインドエンドポイントは変わらず通知され続けるため、バージョンが混在するクラスタでもローリングアップグレード中に接続が維持されます。

クラスタリングが有効な場合、ノード間アイデンティティは必須です。identity_key と identity_key_file は排他的で、いずれか一方が必要です。値は（標準または raw の base64 で）32 バイトの ed25519 シードまたは 64 バイトの ed25519 秘密鍵にデコードされます。trusted_peer_keys は各ノード名をそのノードの 32 バイト ed25519 公開鍵にマッピングし、ローカルの cluster.name に対応するエントリを含み、その値はローカルのアイデンティティと一致していなければなりません。一致しない場合は起動に失敗します。クラスタガイドを参照してください。

Raft（コンセンサス）

有界 Raft コアは、デフォルトで raft.data_dir（~/.wippy/store）の下に永続状態を保存します。再起動したノードはピアからクォーラムに再参加します。store.kv.raft エントリはこのコアを通じてレプリケートされ、ゴシップが bootstrap_expect モデルによるブートストラップを調整します。

単一ノード（開発用）— クラスタリング有効、即座にブートストラップ:

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

3ノード投票クラスタ — 各ノードが他のノードをシードとして指定し、3つ全てが揃うのを待ってからクォーラムを形成。すべてのノードが同一の trusted_peer_keys マップと自身の秘密鍵を持ちます:

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

ゴシップのみのクライアント — 名前付けやメッセージングのためにクラスタに参加するが、Raft は実行しない。これにも自身のアイデンティティが必要で、すべてのノードの信頼マップに含まれている必要があります:

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サーバー。

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

参照: LSPガイド

ネットワークサービス

オーバーレイネットワークマネージャ（SOCKS5、I2P、Tailscaleドライバ）。

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

参照: ネットワークオーバーレイ

HTTPディスパッチャ

HTTP ディスパッチ関数や送信リクエストで使用される共有 HTTP クライアントプールのチューニング。

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

モジュール

wippy install/update で使用されるモジュールレジストリクライアント。

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

拡張機能

起動時に読み込まれるネイティブGoプラグイン拡張機能（Unixのみ）。

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

環境変数

ノード間 TLS

cluster.internode.tls でノード間 TCP mesh の相互 TLS を有効にできます。この mesh 上の relay と Raft の通信も保護されます。既存の cluster 設定に次の設定を追加します。

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 は既定で無効です。enabled: true の場合、空でない 3 つのファイルパスがすべて必要です。PEM 証明書、対応する秘密鍵、server と client の証明書検証に使用する PEM CA bundle を指定します。最小バージョンは TLS 1.2 です。接続するすべての peer に互換性のある証明書と信頼ルートを設定してください。ed25519 identity と trusted peer key map も引き続き必要です。

不明な TLS 設定、不正な型、欠落または不正な認証情報、不正な CA bundle、enabled: true を指定しないファイルパスは起動エラーになります。不正な明示的設定から平文通信へ暗黙にフォールバックすることはありません。

関連項目

• CLIリファレンス — コマンドラインオプション
• クラスタガイド — クラスタリングのアーキテクチャと運用
• エントリ種別 — エントリの種類とフィールド
• 可観測性ガイド — ロギング、メトリクス、トレーシング