Configuration Reference¶

All ByteFreezer services read configuration from a YAML file at startup. Docker images ship with defaults that work for Docker Compose + MinIO deployments — only secrets need to be provided.

Config File Locations¶

Bundled Docker Defaults¶

Docker images include a config.yaml with production-ready defaults:

• S3 endpoint set to minio:9000 (Docker service name)
• Receiver URL set to http://receiver:8080 (Docker service name)
• All secrets (API keys, S3 credentials) are empty strings
• Correct bucket names, ports, and intervals

When deploying with Docker Compose, mount a config file to override the bundled defaults, or pass secrets via environment variables. Config files generated by the MCP tools or installer override these defaults entirely.

Config File vs Volume Mount Priority¶

1. Bundled config (baked into image) — lowest priority
2. Volume-mounted config (e.g., ./config/proxy.yaml:/etc/bytefreezer-proxy/config.yaml:ro) — overrides bundled
3. Environment variables — not currently supported for nested YAML keys due to underscore mapping limitations

Complete Config Keys¶

Proxy¶

Receiver¶

Piper¶

Packer¶

Common Gotchas¶

Config Key Names Differ Between Services¶

S3 config keys are not consistent across services:

Health Reporting Interval Key¶

All services use health_reporting.report_interval (NOT interval_seconds). Using the wrong key name silently defaults to 0, meaning no health reports are sent.

Docker Health Checks¶

Alpine-based images do not include curl. Health checks must use wget:

healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://localhost:8008/api/v1/health"]

Docker Volumes for Packer¶

Packer containers run as uid 1000 and require writable volumes:

volumes:
  - packer-spool:/var/spool/bytefreezer-packer
  - packer-cache:/var/cache/bytefreezer-packer

Container ID Detection¶

Pass HOST_HOSTNAME environment variable for human-readable instance IDs in the control plane:

environment:
  HOST_HOSTNAME: ${HOST_HOSTNAME}

Set HOST_HOSTNAME=myhostname in your .env file. Instance IDs will appear as myhostname:containerid.