Configuration model
HeliosLogs is configured in three layers with a clear precedence. Understanding the model means you'll never be surprised by which value "wins." The exhaustive list of every flag and variable lives in the Configuration reference; this page explains how they combine.
Three layers, one precedence
environment variable > control-plane setting > built-in default
- Environment variable — set at process start. When present, it wins and locks the corresponding field in the admin UI (you can't override an operator's env choice from the browser).
- Control-plane setting — edited in Admin → General, stored in the control plane, and shared across all nodes in a cluster.
- Built-in default — used when neither of the above is set.
Invalid or out-of-range values fall through to the next layer. For example, a tunable below its minimum is treated as unset.
Startup-fixed vs. live-tunable
Settings fall into two groups:
- Startup-fixed — read once when the process starts. Changing them requires a restart. These are CLI flags (
--port,--shared-store, …) and a set of environment variables (the secrets, encryption toggle, admin bootstrap, block compression, ingest queue sizing, syslog port). - Live-tunable — the "server tunables" editable in Admin → General. Editing one applies within seconds — no restart — unless an env var locks it. The one exception is query threads, which is restart-only (the thread pool is built once at startup).
The live tunables are:
| Tunable | Env var | Default |
|---|---|---|
| Compaction interval | HELIOS_BLOCK_COMPACT_SECS | 30 s |
| Compaction target size | HELIOS_BLOCK_TARGET_MB | 64 MB |
| Compaction floor | HELIOS_BLOCK_MIN_COMPACT_MB | 5 MB |
| Small-block waiver count | HELIOS_BLOCK_MAX_SMALL_BLOCKS | 100 |
| Ingest flush rows | HELIOS_BLOCK_FLUSH_ROWS | 50 000 |
| Ingest flush interval | HELIOS_BLOCK_FLUSH_SECS | 5 s |
| Shared-store sync interval | HELIOS_BLOCK_SYNC_SECS | 10 s |
| Retention sweep interval | HELIOS_RETENTION_SWEEP_SECS | 3600 s |
| Aggregation partition budget | HELIOS_AGG_MAX_PARTITIONS | 96 |
| Query result cache | HELIOS_QUERY_CACHE_MB | 1024 MB (0 disables) |
| Query threads (restart-only) | HELIOS_QUERY_THREADS | 4 |
| Session token lifetime | HELIOS_AUTH_TOKEN_TTL_HOURS | 168 h (7 days) |
See Performance tuning for guidance on the storage/query knobs.
Where to set things
| Configuration | Where |
|---|---|
| Bind address, port, data dir, shared store, frontend dir | CLI flags to serve |
| Secrets, encryption, admin bootstrap, control cache | Environment variables only |
| Server tunables (above) | Env var or Admin → General |
| Retention default | HELIOS_RETENTION_DEFAULT_DAYS env, or Admin → General; per-env override under Admin → Environments |
| Theme defaults, appearance | Admin → General |
Inspecting the effective configuration
Admin → General shows two things:
- A read-only runtime config view of startup-fixed settings — including whether each value came from an env var or a default, and the active crypto provider (standard vs. FIPS).
- The server tunables editor, where each row shows the effective value, the configured (control-plane) value, and any env override that is locking it.
This is the quickest way to answer "what is this node actually running with?"
A baseline for small production
A reasonable starting point for a single production node:
# Secrets on persistent, backed-up paths (not under --data-dir)
HELIOS_CONTROL_KEY_PATH=/etc/helios/secret-control.json
HELIOS_JWT_SECRET_PATH=/etc/helios/secret-jwt.json
# Bootstrap an admin on first boot
HELIOS_ADMIN_EMAIL=[email protected]
HELIOS_ADMIN_PASSWORD=... # use a real secret manager
# Keep disk bounded
HELIOS_RETENTION_DEFAULT_DAYS=30
# Shorter sessions if desired (default is 7 days)
HELIOS_AUTH_TOKEN_TTL_HOURS=24Leave the storage/query tunables at their defaults until you have a reason to change them.