# Startup configuration reference

Startup settings choose what a Smeltr process runs, where it listens and where it keeps its state. They come from `smeltr.toml` or the environment and apply on restart.

## Before you start

Browsers and workers reach the configured leader listener (443 by default), or an HTTPS proxy (usually 443). Workers also need access to each source and destination's configured endpoints. Workers initiate heartbeats and Git configuration fetches; they need no inbound worker management connection from the leader. Ports and protocols for data systems come from their connector configuration, not a universal Smeltr port list.

Protect leader state and sealing keys, plus worker identity, credentials and trust files. See [Backup and recovery](/docs/backup-recovery). Use the startup reference for the version you received: settings can change between deliveries, and documentation for another version may not match your artifact.

## Settings

`leader.http.port` env `SMELTR_GUI_PORT`  default `443`

The port browsers and workers connect to, 1 to 65535. On Linux, grant the service `CAP_NET_BIND_SERVICE` to listen on a port below 1024.

Examples:

- `8443`
- `8080`

`leader.http.bind` env `SMELTR_GUI_BIND`  default `127.0.0.1`

The address the leader listens on. `0.0.0.0` listens on every IPv4 interface.

Examples:

- `0.0.0.0`
- `10.0.4.12`
- `::`

`leader.http.public_origin` env `SMELTR_PUBLIC_ORIGIN`  default from `bind` and `tls.enabled`

The scheme, host and port browsers use. Several origins, separated by commas, must share one scheme.

Examples:

- `https://smeltr.example.com`
- `https://smeltr.example.com,https://smeltr.internal:8443`

`leader.enabled` env `SMELTR_LEADER_ENABLED`  default `false`

Whether this process runs the leader.

Example:

- `true`

`leader.storage.data_dir` env `SMELTR_LEADER_DATA_DIR`  default `smeltr-leader-data`

The directory holding `leader.db`, `repos/` and `tls/`.

Examples:

- `/var/lib/smeltr/leader`
- `data/leader`

`leader.secrets.key` env `SMELTR_LEADER_SECRET_KEY`  default `smeltr-leader-secrets/sealing.key`

The key that seals stored secrets. Keep it out of routine data archives.

Example:

- `/etc/smeltr/sealing.key`

`leader.secrets.versions` env `SMELTR_LEADER_SECRET_VERSIONS`  default `5`

How many changes to a secret a rollback reaches back, counted on every branch: at least 1, or -1 for every version. An older version is gone unless a running deployment uses it.

Examples:

- `10`
- `-1`

`leader.lookups.versions` env `SMELTR_LEADER_LOOKUP_VERSIONS`  default `5`

How many uploads of a lookup file a rollback reaches back, counted on every branch: at least 1, or -1 for every version. An older one is gone unless a branch or running deployment uses it.

Examples:

- `10`
- `-1`

`leader.tls.enabled` env `SMELTR_LEADER_TLS`  default `true`

Whether the leader serves HTTPS itself. Set `false` only behind a private proxy or for a local test.

Example:

- `false`

`leader.tls.extra_san` env `SMELTR_LEADER_TLS_EXTRA_SAN`  default none

More names for the leader's certificate: a TOML array, or a comma-separated environment value.

Examples:

- `leader.internal`
- `leader.internal,10.0.4.12`

`leader.tls.ca_validity` env `SMELTR_LEADER_CA_VALIDITY`  default `3650d`

How long a newly created CA is valid, 1 day to 100 years. An existing CA keeps its own.

Examples:

- `365d`
- `8760h`

`leader.tls.acme_http_port` env `SMELTR_ACME_HTTP_PORT`  default `80`

The port the leader answers a certificate authority's HTTP-01 challenge on, while it orders a certificate. Authorities connect to 80; set another only when something forwards 80 to it.

Example:

- `8080`

`leader.recover_admin` env `SMELTR_RECOVER_ADMIN`  default `false`

`true` regenerates the built-in administrator's password on this start. Remove it before the next restart.

Example:

- `true`

`worker.enabled` env `SMELTR_WORKER_ENABLED`  default `false`

Whether this process runs a worker. With `leader.enabled`, one process runs both.

Example:

- `true`

`worker.group` env `SMELTR_WORKER_GROUP`  default `default`

The worker group it joins. It must name a deployed group.

Examples:

- `edge`
- `dmz-collectors`

`worker.zone` env `SMELTR_WORKER_ZONE`  default unset

The availability zone this worker runs in, for connectors that prefer their own zone.

Example:

- `eu-west-1a`

`worker.listen_address` env `SMELTR_WORKER_LISTEN_ADDRESS`  default `::`

The address every receiver on this worker listens on. :: is all IPv4 and IPv6 addresses.

Examples:

- `10.0.0.5`
- `127.0.0.1`

`worker.leader.url` env `SMELTR_LEADER_URL`  default unset

The leader's address. Required for a separate worker; a worker in the leader's process finds its leader itself.

Examples:

- `https://smeltr.example.com`
- `https://10.0.4.12:8443`

`worker.leader.ca` env `SMELTR_LEADER_CA`  default unset

A CA file the worker trusts for the leader. An enrollment code sets up trust without one.

Example:

- `/etc/smeltr/leader-ca.pem`

`worker.storage.state_dir` env `SMELTR_WORKER_STATE_DIR`  default `smeltr-worker-data`

The directory holding a separate worker's identity, credential, trusted certificates and configuration repository. A worker in the leader's process uses `worker/` under `leader.storage.data_dir`.

Example:

- `/var/lib/smeltr/worker`

`worker.runtime.thread_limit` env `SMELTR_WORKER_THREAD_LIMIT`  default the available cores

How many threads process records. Other threads in the process are not counted.

Examples:

- `4`
- `16`

`worker.runtime.memory` env `SMELTR_WORKER_MEMORY`  default the container's memory limit

The memory the worker sizes its columnar budget and every unset `bufferBytes` to. A worker in the leader's process sizes to this only, never to its container's limit. Without either, each keeps its default.

Examples:

- `4GiB`
- `16 GB`

`worker.heartbeat.interval_ms` env `SMELTR_WORKER_HEARTBEAT_INTERVAL_MS`  default `1500`

Milliseconds between the worker's reports to the leader.

Examples:

- `1000`
- `5000`

`worker.heartbeat.stop_after_unreachable_secs` env `SMELTR_WORKER_STOP_AFTER_UNREACHABLE_SECS`  default unset

Seconds without a heartbeat reaching the leader after which the worker stops its deployment. Unset, it never does, so a leader outage never stops data flowing.

Examples:

- `300`
- `3600`

`worker.enrollment_code` env `SMELTR_WORKER_ENROLLMENT_CODE`  default unset

The code a worker enrolls with, and enrolls again with if the leader forgets it.

Example:

- `smeltrenroll-1-system-aaaa-bbbb`

`worker.metrics_endpoint.enabled` env `SMELTR_WORKER_METRICS_ENDPOINT_ENABLED`  default `false`

Whether this worker opens a port serving `/metrics` for Prometheus to scrape.

Example:

- `true`

`worker.metrics_endpoint.port` env `SMELTR_WORKER_METRICS_ENDPOINT_PORT`  default `9464`

The port the metrics endpoint listens on, at `worker.listen_address`.

Example:

- `9100`

`worker.metrics_endpoint.tls_cert` env `SMELTR_WORKER_METRICS_ENDPOINT_TLS_CERT`  default unset

The certificate the metrics endpoint serves TLS under, as a PEM file, leaf first.

Example:

- `/etc/smeltr/metrics.pem`

`worker.metrics_endpoint.tls_key` env `SMELTR_WORKER_METRICS_ENDPOINT_TLS_KEY`  default unset

The unencrypted PEM private key of `tls_cert`.

Example:

- `/etc/smeltr/metrics-key.pem`

`worker.metrics_endpoint.client_ca` env `SMELTR_WORKER_METRICS_ENDPOINT_CLIENT_CA`  default unset

Require scrapers to present a certificate chaining to these PEM roots. Needs TLS.

Example:

- `/etc/smeltr/scraper-ca.pem`

`worker.metrics_endpoint.user` env `SMELTR_WORKER_METRICS_ENDPOINT_USER`  default unset

Require scrapers to sign in with basic auth as this user, with `password`.

Example:

- `prometheus`

`worker.metrics_endpoint.password` env `SMELTR_WORKER_METRICS_ENDPOINT_PASSWORD`  default unset

The basic auth password for `user`. Without TLS it crosses the network in clear.

Example:

- `s3cret`

`log_level` env `SMELTR_LOG_LEVEL`  default `info`

The lowest severity logged. A top-level key.

`error`

Logs errors.

`warn`

Logs warnings and errors.

`info`

Logs info, warnings and errors.

`debug`

Logs everything but trace.

`trace`

Logs everything.

## How it works

Set `SMELTR_CONFIG_FILE` to an absolute file path to choose the startup file. Otherwise Smeltr looks for `./smeltr.toml` in its working directory. Relative state paths are also relative to that working directory. A non-empty environment variable overrides the file, which overrides the default. Smeltr treats empty environment values as unset. Invalid values and unknown TOML keys fail startup.

In `smeltr.toml`, each setting sits under the table its key names. The examples above are environment values: in the file a string is quoted and a list is an array.

```
# A leader that browsers reach at
# https://smeltr.example.com.
log_level = "info"

[leader]
enabled = true

[leader.http]
port = 8443
bind = "0.0.0.0"
public_origin = "https://smeltr.example.com"

[leader.tls]
extra_san = ["leader.internal"]

[leader.storage]
data_dir = "/var/lib/smeltr/leader"

[leader.secrets]
key = "/etc/smeltr/sealing.key"
versions = 10
```

Every startup setting applies when the process restarts. An existing CA keeps its stored validity period. A worker uses enrollment codes only while it holds no credential its leader knows.

At least one of `leader.enabled` and `worker.enabled` must be true.

## Other settings

Settings outside the startup file change elsewhere:

| Change | Where | Takes effect |
| --- | --- | --- |
| Accounts | Admin → Accounts | Immediately |
| Session limits | Admin → System → Sessions | On the next session request |
| Pipelines and group configuration | A branch → Open for review → Approve & deploy | When workers adopt the deployment |
| Certificates | Admin → System → Certificates | On reload; restart if the UI reports failure |

## See also

-   [Backup and recovery](/docs/backup-recovery)
-   [Change log verbosity](/docs/operations#logs)