config.example.yaml

log:
  # Set the log level. Supported levels:
  #
  # - trace
  # - debug
  # - info
  # - warn
  # - error
  # - fatal
  # - panic
  #
  level: "error"
# Analytics configuration
analytics:
  reporting:
    # Enable reporting anonymous usage statistics (DB type, Lock type, Total Size)
    # to the project maintainers
    enabled: true
# OpenTelemetry support.
opentelemetry:
  enabled: true
  # Configure open telemetry to connect to a collector with the grpc URL. If
  # not set, ncps will simply print telemetry to stdout which is not very
  # useful but can be helpful for debugging.
  grpc-url: "http://otelcol-collector.monitoring.svc:4317"
# Prometheus metrics exposed at /metrics on the same port as ncps
prometheus:
  enabled: true
# Configure the cache functionality.
cache:
  # Whether to allow the DELETE verb to delete narInfo and nar files
  allow-delete-verb: true
  # Whether to allow the PUT verb to push narInfo and nar files directly
  allow-put-verb: true
  # Optional Bearer token required to access GET and HEAD routes. When set,
  # requests without a matching "Authorization: Bearer <token>" header are
  # rejected with 401 Unauthorized. /healthz and /metrics are always exempt;
  # PUT and DELETE are unaffected. Leave empty (the default) to serve reads
  # without authentication. Env: CACHE_GET_TOKEN.
  get-token: ""
  # The hostname of the cache server
  hostname: "ncps.mycompany.tld"
  # Download configuration
  download:
    # Timeout for polling storage when waiting for download completion by another server
    poll-timeout: 30s
  # The URL of the database
  # Supports multiple database engines via URL scheme:
  #   SQLite:     sqlite:/var/lib/ncps/db/db.sqlite
  #   PostgreSQL: postgresql://user:password@localhost:5432/ncps?sslmode=require
  #   PostgreSQL: postgres://user:password@localhost:5432/ncps?sslmode=require
  #   PostgreSQL (local dev, no SSL): postgresql://user:password@localhost:5432/ncps?sslmode=disable
  #   MySQL/MariaDB: mysql://user:password@localhost:3306/ncps
  database-url: "sqlite:/var/lib/ncps/db/db.sqlite"
  # Database connection pool configuration (optional)
  # Tune these based on your database server capacity and application workload
  database:
    pool:
    # Maximum number of open connections to the database
    # If not set or 0, defaults are used based on database type:
    #   SQLite: 1 (required to avoid "database is locked" errors)
    #   PostgreSQL: 25
    #   MySQL/MariaDB: 25
    # max-open-conns: 25
    # Maximum number of idle connections in the pool
    # If not set or 0, defaults are used based on database type:
    #   SQLite: not configured (uses Go's default)
    #   PostgreSQL: 5
    #   MySQL/MariaDB: 5
    # max-idle-conns: 5
  # CDC (Content-Defined Chunking) configuration (EXPERIMENTAL)
  # Enables deduplication of NAR files by splitting them into content-defined chunks.
  # Chunks are stored in the same backend as NAR files (different prefix/directory).
  #
  # Choosing CDC vs. whole-file serving: CDC trades disk usage (via dedup) for many
  # small random reads per NAR when serving. That trade pays off on low-latency
  # storage (local SSD, NVMe-backed object stores). On high-latency or spinning-disk
  # backends — especially a network filesystem — the extra small reads dominate and
  # whole-file serving is more robust; prefer leaving CDC disabled there.
  cdc:
    # Enable CDC chunking
    enabled: false
    # Minimum chunk size for CDC in bytes (default: 16384)
    min: 16384
    # Average chunk size for CDC in bytes (default: 65536)
    avg: 65536
    # Maximum chunk size for CDC in bytes (default: 262144)
    max: 262144
    # Maximum time progressive CDC streaming waits for the next chunk to be
    # produced/become readable before failing the transfer (default: 30s). Keep it
    # below your reverse-proxy gateway timeout so a stalled chunk on high-latency
    # storage surfaces as a retryable error to the client rather than a gateway 504.
    chunk-wait-timeout: 30s
  # In-flight NAR staging: serve a NAR cross-pod while it is still downloading by
  # staging it to shared storage as part-objects once another replica waits for it.
  # An HA-safe alternative to CDC. Only active with a distributed (Redis) lock.
  inflight-staging:
    # Enable in-flight staging (default: false)
    enabled: false
    # Grace period to retain staging part-objects after the NAR's final
    # representation is committed, so in-flight readers drain first (default: 5m)
    retention: 5m
    # Size in bytes of each staging part-object, a transport unit distinct from
    # CDC chunk sizes (default: 8388608 = 8 MiB)
    part-size: 8388608
  # The maximum size of the store. It can be given with units such as 5K, 10G
  # etc. Supported units: B, K, M, G, T
  max-size: 100G
  # Configure the LRU to clean the store and purge least used nars. No nars are
  # removed unless the size approaches max-size.
  lru:
    # The cron spec for cleaning the store. Refer to
    # https://pkg.go.dev/github.com/robfig/cron/v3#hdr-Usage for documentation
    schedule: "0 0 * * *"
    # The name of the timezone to use for the cron
    timezone: America/Los_Angeles
  # The path to the secret key used for signing cached paths
  # XXX: Only set this if you intend to store the key yourself instead of having ncps store it in its config store.
  secret-key-path: ""
  # Whether to sign narInfo files or passthru as-is from upstream
  sign-narinfo: true
  # Reject narInfos uploaded via PUT that do not carry a signature trusted by
  # the configured trusted-upload-keys (fail-closed). When enabled, uploads are
  # rejected if no signature validates against a trusted upload key, and also
  # rejected when no trusted upload keys are configured at all. Upload-trust is
  # independent of the upstream public keys below (which govern what ncps pulls):
  # to accept your own builds, sign them (nix `secret-key-files`) and list the
  # matching public key in trusted-upload-keys. Default off preserves
  # backward-compatible passthru of client uploads.
  require-trusted-signature: false
  # Public keys (nix-format name:base64) that authorize PUT uploads when
  # require-trusted-signature is enabled. Independent of upstream public keys.
  trusted-upload-keys: []
  #   - my-cache-1:abcdef0123456789...=
  storage:
    # The local data path used for configuration and cache storage
    # Use this OR S3 storage (cache.storage.s3.bucket) - not both
    local: "/var/lib/ncps"
    # S3 Storage configuration (alternative to cache.storage.local)
    # Use this for storing cache data in S3-compatible storage (AWS S3, Garage, etc.)
    # s3:
    #   # S3 bucket name (use this OR cache.storage.local - not both)
    #   bucket: "ncps-cache"
    #   # S3-compatible endpoint URL with scheme (e.g., https://s3.amazonaws.com or http://garage.example.com:3900)
    #   endpoint: "https://s3.amazonaws.com"
    #   # AWS region (optional)
    #   region: "us-east-1"
    #   # S3 access key ID
    #   access-key-id: "your-access-key"
    #   # S3 secret access key
    #   secret-access-key: "your-secret-key"
    #   # Force path-style S3 addressing (required for Garage and other self-hosted S3 servers, optional for AWS S3)
    #   # Set to true for Garage and other self-hosted S3-compatible servers
    #   # Set to false for AWS S3 (default)
    #   force-path-style: false
  # The path to the temporary directory that is used by the cache to download NAR files
  temp-path: "/tmp"
  # Path to netrc file for upstream authentication
  netrc-file: "/etc/ncps/netrc"
  # Configure upstream caches
  upstream:
    # Set to URL (with scheme) for each upstream cache
    urls:
      - https://cache.nixos.org
      - https://nix-community.cachix.org
    # Set to host:public-key for each upstream cache
    public-keys:
      - cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
      - nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=
    # Timeout for establishing TCP connections to upstream caches (default: 3s)
    # Increase this if you experience connection timeouts with slow networks
    dialer-timeout: 3s
    # Timeout for waiting for upstream server's response headers (default: 3s)
    # Increase this if you see "timeout awaiting response headers" errors
    response-header-timeout: 3s
  # Redis configuration for distributed locking (OPTIONAL - for HA deployments only)
  # If not configured, local locks are used (single-instance mode)
  redis:
    # List of Redis server addresses (omit this entire section to use local locks)
    # For single node: ["localhost:6379"]
    # For cluster: ["node1:6379", "node2:6379", "node3:6379"]
    addrs:
      - "localhost:6379"
    # Username for authentication (optional, required for Redis ACL)
    username: ""
    # Password for authentication (optional)
    password: ""
    # Database number (0-15)
    db: 0
    # Enable TLS connection
    use-tls: false
    # Connection pool size (default: 10)
    pool-size: 10
  # Lock configuration
  lock:
    # Lock backend selection (optional)
    # Options: "local" (default), "redis"
    # - local: In-memory locks (single instance only)
    # - redis: Distributed locks using Redis (requires cache.redis.addrs)
    # backend: "local"

    # Redis-specific lock settings (only used when backend is "redis")
    redis:
      # Key prefix for all distributed locks (default: "ncps:lock:")
      key-prefix: "ncps:lock:"
    # Timeout for download locks (per-hash locks)
    download-lock-ttl: 5m
    # Timeout for LRU lock (global exclusive lock)
    lru-lock-ttl: 30m
    # Retry configuration for distributed locks
    retry:
      # Maximum number of retry attempts
      max-attempts: 3
      # Initial retry delay
      initial-delay: 100ms
      # Maximum retry delay (exponential backoff caps at this)
      max-delay: 2s
      # Enable jitter to prevent thundering herd
      jitter: true
    # Degraded mode: allow falling back to local locks if Redis is unavailable
    # WARNING: Only enable in emergencies - breaks HA guarantees
    allow-degraded-mode: false
# Configure the main server
server:
  # The address of the server
  addr: ":8501"