설정 레퍼런스

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 재정의 순서로 적용됩니다. 팩에서 실행되는 애플리케이션의 경우 팩된 런타임 기본값은 이 세 단계보다 우선순위가 낮습니다. 런타임 기본값 게시를 참고하세요.

프로파일 {#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

참조: Logger 모듈

프로파일러

CPU/메모리 프로파일링을 위한 Go pprof HTTP 서버. -p 플래그 또는 설정으로 활성화.

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

기본 주소로 활성화하면 http://localhost:6060/debug/pprof/에서 프로파일러에 접근할 수 있습니다.

보안

전역 보안 동작입니다. 개별 정책은 security.policy 엔트리로 정의됩니다.

security:
  strict_mode: false

참조: 보안 시스템, 보안 모듈

레지스트리

엔트리 스토리지 및 버전 히스토리. 레지스트리는 모든 설정 엔트리를 보유합니다.

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

레지스트리 검색 캐싱. 엔트리 조회에 내부적으로 사용.

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를 노출합니다.

참조: 관측성 가이드

클러스터

멀티 노드 클러스터링은 gossip 멤버십과 제한된 Raft 합의 코어로 구성됩니다. 아키텍처와 운영 모델은 클러스터 가이드를 참고하세요. 이 섹션은 설정 키 레퍼런스입니다.

최상위

멤버십 (gossip)

memberlist를 통한 SWIM gossip. 노드 디스커버리, 장애 감지, 메타데이터 전파에 사용됩니다.

Gossip 시크릿은 필수입니다. membership.secret_key 또는 membership.secret_file을 설정하세요(둘 다 주어지면 파일이 우선합니다); 둘 다 없으면 클러스터 컴포넌트가 시작에 실패합니다. 값은 base64로 인코딩됩니다.

네 개의 프로브 키는 설정되지 않으면 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 엔트리는 이 코어를 통해 복제되며, gossip은 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노드 voting 클러스터 — 각 노드가 다른 노드를 시드로 나열하고 쿼럼을 형성하기 전에 세 노드 모두를 기다림. 모든 노드가 동일한 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

Gossip 전용 클라이언트 — 명명/메시징을 위해 클러스터에 참여하지만 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이면 비어 있지 않은 파일 경로 세 개가 모두 필요합니다. PEM 인증서, 일치하는 개인 키, server 및 client 인증서를 검증할 PEM CA bundle을 지정합니다. 최소 버전은 TLS 1.2입니다. 연결할 모든 peer에 호환되는 인증서와 신뢰 루트를 구성해야 합니다. ed25519 identity와 신뢰할 peer key map도 계속 필요합니다.

알 수 없는 TLS 설정, 잘못된 타입, 누락되거나 잘못된 인증 정보, 잘못된 CA bundle, enabled: true 없이 제공된 경로는 시작을 실패하게 합니다. 잘못된 명시적 설정이 평문 통신으로 자동 전환되지는 않습니다.

참고

• CLI 레퍼런스 - 커맨드라인 옵션
• 클러스터 가이드 - 클러스터링 아키텍처 및 운영
• 엔트리 종류 - 엔트리 타입과 필드
• 관측성 가이드 - 로깅, 메트릭, 트레이싱