Configure a deployment

Start from the configuration generated by your server version. Edit the settings needed for your deployment and keep the other required fields. The field reference lists accepted keys, types and schema defaults; deployment examples can use different values.

Configuration file

Shell

# Generate or use config.yaml in the current directory
./boilstream

# Use an existing configuration file
./boilstream --config /etc/boilstream/config.yaml

# Or select it through the environment
CONFIG_FILE=/etc/boilstream/config.yaml ./boilstream

Supported environment overrides take precedence over YAML values. Use the options provided by your installed version; arbitrary environment-variable names do not become settings.

Keep the generated base file complete. The excerpts in these guides show individual changes, not a complete production configuration.

Storage configuration

Choose a real storage backend before relying on persisted history. The noop backend is for development and provides no object-storage durability.

For S3, configure a primary backend with backend_type: s3, the bucket, prefix and region. Use use_path_style only when required by the endpoint.

Supply credentials using your deployment’s credential mechanism. For a compatible service such as MinIO, set its endpoint and the addressing mode required by that service. See AWS IAM permissions before provisioning AWS storage.

Keep the primary data storage and configured recovery storage available. Do not rename, delete or directly modify service-managed objects. Retain the encryption keys required to read existing data and backups.

Network interfaces

Setting	Purpose
auth_server.port	Login, dashboard and authenticated administration
pgwire.port	PostgreSQL wire-protocol SQL clients
kafka.port	Kafka producers and preview consumers
http_ingestion.port	HTTP Arrow ingestion and preview SSE
server.flight_base_port	Flight deployment configuration
server.consumer_flight_port	FlightSQL query service
metrics.port	Monitoring endpoint

Use the endpoint returned by the dashboard or supplied by the operator, especially in a cluster. A configured port alone does not establish a supported client workflow. See Interface compatibility.

Configure TLS separately for the enabled interfaces. Use trusted certificates for public clients. Keep monitoring and administrative interfaces restricted to the appropriate network and users.

Authentication and authorization

Configure the login methods your organization uses, then assign tenant membership and catalog permissions. Authentication and catalog authorization are separate controls. See Authentication and Catalog sharing.

The Schema Registry is served under /schema-registry on the auth server. Every request requires a Schema Registry bearer token; the Kafka ingest token is not interchangeable. See Schema Registry.

HTTP/2 ingestion configuration

Enable the HTTP interface and allow only the browser origins that need access. Use the field reference for accepted HTTP settings. Applications must use binary Arrow IPC and inspect the admitted row count; see HTTP ingestion.

Data visibility and sizing

duckdb_persistence.commit_interval_ms schedules local commits; processing.snapshot_interval_minutes controls file completion. These scheduling intervals are not end-to-end latency guarantees.

Local commit and publication to stored history happen at different times. Size recent-data retention, batches and storage capacity using your workload. Use the generated defaults for advanced tuning unless measurements show a need to change them. See Reliability and completion.

Optional features

• Full-text search: enable the service, then the required tables and text fields.
• Hydration: preload historical files for repeated reads.
• Metrics: configure the scrape endpoint and monitoring.
• Audit logging: choose the destination and whether queries and IP addresses should be included. Audit logging alone does not establish a compliance certification.

Cluster mode configuration

Use the Kubernetes profile for the production cluster setup. It includes replica count, service endpoints, TLS, storage and recovery settings. A shared bucket alone does not establish a safe cluster configuration.

Keep stable cluster identity and key material across restarts. Follow Cluster mode for quorum requirements and deliberate recovery; do not bootstrap an existing deployment as an empty new cluster.

Validation and upgrades

The server validates configuration at startup. Correct reported errors before admitting production traffic. A YAML file parsing successfully does not prove that its storage, certificates or credentials work.

When upgrading, review the migration before applying it:

Shell

./boilstream --upgrade-config config.yaml --dry-run

Keep a backup of the previous configuration and follow the migration instructions for the release. Use boilstream-admin for server and CLI configuration commands; they manage different settings.

Complete configuration example

Small configuration excerpt

Merge only the settings you need into the generated file. For example, these values schedule commits and historical-file completion; they do not guarantee delivery within those intervals.

YAML

duckdb_persistence:
  commit_interval_ms: 1000
processing:
  snapshot_interval_minutes: 10

Verify and recover

Validate the complete configuration with the matching release, start the service, inspect effective settings with boilstream-admin config dump, and test login, a small write/read workflow and configured object storage. If verification fails, stop the rollout and restore the previous configuration and compatible binary. Preserve stable encryption keys and cluster identity.