STREAMING_HUB_ENV selects the environment. The staging and production values are hardened environments: they refuse the local shortcuts that the Required column marks as “Hardened”. A duration value uses Go syntax, such as 30s, 5m, or 720h. The d unit does not exist, so write 2160h for 90 days.
Core
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_ENV | Environment: local, staging, or production. The hub refuses any other value, and it refuses a variable that is set but blank. | local | No |
STREAMING_HUB_ROLE | Part of the hub that this process runs: all, ingest, or delivery. An unknown value logs a warning and runs all. | all | No |
STREAMING_HUB_HTTP_LISTEN_ADDR | Bind address of the HTTP API. | :8080 | No |
STREAMING_HUB_LOG_LEVEL | Log level. | info | No |
STREAMING_HUB_SHUTDOWN_TIMEOUT | Time the hub allows for work in progress to finish when it stops. It must be below 35s, or the startup fails. | 30s | No |
STREAMING_HUB_PRE_STOP_DRAIN_TIMEOUT | Time the hub waits after it reports not ready and before it stops. 0 turns off the wait. | 5s | No |
STREAMING_HUB_SWAGGER_ENABLED | Serves the OpenAPI specification and its documentation page. | false | No |
Database
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_POSTGRES_DSN | PostgreSQL connection string. Hardened environments require a DSN that verifies the server: sslmode=verify-full, or verify-ca with sslrootcert. A Unix socket host is accepted. Sensitive. | — | Yes |
STREAMING_HUB_ALLOW_INSECURE_DB_TLS | Accepts a DSN that does not verify the server in a hardened environment. | false | No |
STREAMING_HUB_POSTGRES_MAX_OPEN_CONNS | Maximum open connections. It must be greater than 0. When unset, the default depends on the role. | 25 (all), 8 (ingest), 16 (delivery) | No |
STREAMING_HUB_POSTGRES_MAX_IDLE_CONNS | Idle connections kept open. It must be 0 or more. When unset, the default depends on the role. | 12 (all), 4 (ingest), 10 (delivery) | No |
STREAMING_HUB_POSTGRES_CONN_MAX_LIFETIME | Time before the hub replaces a connection. | 30m | No |
Dispatcher
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_DISPATCH_WORKERS | Delivery workers. The hub caps the value at the open connections minus 4, with a minimum of 1. | 8 | No |
STREAMING_HUB_DISPATCH_IDLE_INTERVAL_MS | Milliseconds a worker waits after it finds no job. | 250 | No |
STREAMING_HUB_POISON_THRESHOLD | Times the recovery sweep can take back a job after a worker crash, with no delivery result, before the hub dead-letters the job as poison. | 5 | No |
Rate limiting
The hub meters reads per tenant in a Redis counter store.| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_REDIS_ADDRESS | Address of the counter store. | — | Yes |
STREAMING_HUB_REDIS_PASSWORD | Password of the counter store. Sensitive. | — | No |
STREAMING_HUB_REDIS_TLS | Uses TLS for the counter store. | true | Hardened: true |
STREAMING_HUB_REDIS_CA_CERT | CA bundle for that TLS connection, as base64 PEM. | — | No |
RATE_LIMIT_ENABLED | Turns on the rate limiter. The hub refuses to start without true. | false | Yes: true |
ALLOW_RATELIMIT_FAIL_OPEN | Behavior when the counter store is unreachable. With true, reads continue without a limit. With false, the limited routes answer 503. | false | No |
ALLOW_INSECURE_TLS | Turns off the TLS requirement on every client that the shared library builds in this process. It is for local work only. | — | Hardened: not true |
RATE_LIMIT_REDIS_TIMEOUT_MS | Milliseconds one counter update can take before the request stops waiting for the store. | 500 | No |
STREAMING_HUB_PULL_RATE | Reads per second for each tenant on GET /v1/events. | 100 | No |
STREAMING_HUB_DASHBOARD_RATE | Requests per minute for each tenant on the two dashboard reads. | 60 | No |
STREAMING_HUB_READ_RATE | Requests per minute for each tenant on the Console reads: subscriptions, endpoint, health, setup artifacts, and catalog. | 60 | No |
License
| Variable | Description | Default | Required |
|---|---|---|---|
LICENSE_KEY | Lerian license key. The hub checks it at startup in every environment. Sensitive. | — | Yes |
ORGANIZATION_IDS | License scope. The value must be global. | — | Yes |
IS_DEVELOPMENT | With true, the hub checks the license against the development license server. | — | production: not true |
Tenancy
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_TENANT_ID | Tenant of a single-tenant hub. Letters, digits, -, and _, with a letter or digit first. It must match the ce-tenantid that the producers put on their events. Multi-tenant mode ignores it and logs a warning. | — | Single-tenant mode |
STREAMING_HUB_DELEGATED_SCOPE_CLAIM | Name of the token claim that carries a caller’s delegated scope. | atua_por | No |
STREAMING_HUB_DELEGATED_KIND_CLAIM | Name of the token claim that carries the credential type of a scoped caller. | nature | No |
Dashboard and health
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_DASHBOARD_CURSOR_HMAC_KEY | Key that signs the dashboard page cursors. Standard base64 of exactly 32 bytes. A new key makes the cursors in use invalid. Hardened environments refuse the published development key. Sensitive. | — | Yes |
STREAMING_HUB_HEALTH_WINDOW | Longest period that the subscription health view measures. | 720h | No |
Secrets
The hub encrypts the webhook signing secrets that it stores with a key-encryption key (KEK).| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_KEK_SOURCE | KEK source: env or secretsmanager. With both values, the hub reads the KEK from the variable that STREAMING_HUB_KEK_REF names. With secretsmanager, the deploy layer puts the managed secret in that variable. | env | No |
STREAMING_HUB_KEK_REF | Name of the variable that holds the KEK. That variable must not be empty, and the key must be at least 32 bytes. Hardened environments refuse the published development key. | — | Yes |
Kafka
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_KAFKA_BROKERS | Kafka brokers (CSV). | — | Yes |
STREAMING_HUB_KAFKA_SCRAM_MECHANISM | SCRAM mechanism: SCRAM-SHA-256 or SCRAM-SHA-512. It requires TLS. | — | No |
STREAMING_HUB_KAFKA_SCRAM_USERNAME | SCRAM user. | — | With a SCRAM mechanism |
STREAMING_HUB_KAFKA_SCRAM_PASSWORD | SCRAM password. Sensitive. | — | With a SCRAM mechanism |
STREAMING_HUB_KAFKA_TLS_ENABLED | Uses TLS for Kafka. | false | No |
STREAMING_HUB_KAFKA_CA_CERT | CA certificate for Kafka TLS. | — | No |
STREAMING_HUB_ALLOW_INSECURE_KAFKA | Allows plaintext Kafka. A connection without TLS needs it. | false | Hardened: false |
STREAMING_HUB_DLQ_RETENTION | Time the hub keeps a dead-letter observation. | 168h | No |
STREAMING_HUB_DLQ_PRUNE_INTERVAL | Time between removals of expired dead-letter observations. 0 or less turns off the removal. | 1h | No |
Telemetry
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_METRICS_ENABLED | Turns on OpenTelemetry. | true | No |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP collector endpoint. When empty, the hub sends no telemetry. | — | No |
OTEL_INSECURE_EXPORTER | Sends telemetry without TLS. | false | No |
ALLOW_INSECURE_OTEL | Allows a plaintext exporter when STREAMING_HUB_ENV is production. Without it, that case stops the startup. | — | No |
Catalog
A single-tenant hub reads the event catalog from the producers inSTREAMING_HUB_MANIFEST_SOURCES. A multi-tenant hub finds its producers from the credentials of each tenant.
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_MANIFEST_SOURCES | Producer base URLs (CSV), as scheme://host[:port] with no path. Multi-tenant mode refuses it. An invalid entry stops the startup. | — | No |
STREAMING_HUB_MANIFEST_CLIENT_ID | Client ID that the hub uses to read protected manifests. Set it together with the secret, or set neither. | — | No |
STREAMING_HUB_MANIFEST_CLIENT_SECRET | Client secret for those reads. Sensitive. | — | No |
STREAMING_HUB_MANIFEST_REFRESH_INTERVAL | Seconds between catalog refreshes. | 300 | No |
Topic reconciler
The reconciler compares topics, subscriptions, and the catalog, and reports differences in metrics and logs. It changes nothing.| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_RECONCILER_ENABLED | Runs the reconciler. | true | No |
STREAMING_HUB_RECONCILER_INTERVAL | Seconds between reconciler passes. | 300 | No |
Partitions and history
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_PARTITION_CRON_INTERVAL | Time between runs that create future partitions. | 6h | No |
STREAMING_HUB_PARTITION_FUTURE_BUFFER_WEEKS | Weekly partitions that the hub keeps ready ahead of time. It must be at least 1. | 4 | No |
STREAMING_HUB_PARTITION_RETENTION_ENABLED | Drops expired partitions. With false, the hub drops none. | false | No |
STREAMING_HUB_PARTITION_RETENTION_HORIZON | Age at which a partition expires. With retention on, it must be at least the future buffer weeks times seven days, and an invalid value stops the startup. | 2160h | No |
STREAMING_HUB_ARCHIVE_BUCKET | S3 bucket name for archived delivery history. Use the bare name. When empty, archiving is off. After a replica starts with a bucket, retention purges only history that reached the archive. Clearing the variable later does not remove that rule. | — | No |
STREAMING_HUB_HISTORY_RETENTION_ENABLED | Keeps a short delivery history: the hub drops hot data after it is archived. It requires partition retention and the archive bucket. After the hub records this mode, the mode is permanent. | false | No |
Idempotency
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_IDEMPOTENCY_TTL | Time a committed response stays available for replay with the same X-Idempotency key. | 24h | No |
STREAMING_HUB_IDEMPOTENCY_REAP_INTERVAL | Time between removals of expired idempotency records. 0 or less turns off the removal. | 5m | No |
Endpoint auto-disable
The hub turns off a subscription when its deliveries fail for a long and spread period. One successful delivery resets the count.| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_AUTODISABLE_ENABLED | Turns on automatic disable. | true | No |
STREAMING_HUB_AUTODISABLE_FAILURE_WINDOW | Minimum time since the first failure. | 120h | No |
STREAMING_HUB_AUTODISABLE_FAILURE_SPREAD | Minimum time between the first and the last failure. | 12h | No |
Authentication
| Variable | Description | Default | Required |
|---|---|---|---|
PLUGIN_AUTH_ENABLED | Turns on Access Manager authentication. | true | Hardened: true |
PLUGIN_AUTH_ADDRESS | Access Manager address. | http://localhost:4000 | No |
AUTH_REQUIRED | With true, protected routes answer 503 when authentication is off or the Access Manager address is empty. | false | No |
AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED | With true and authentication off, protected routes still require a bearer token and answer 401 without one. They do not call Access Manager. Without AUTH_JWT_VERIFY_CERT or AUTH_JWT_VERIFY_CERT_PATH, the hub does not check the token signature. | false | No |
AUTH_M2M_INVERSION_ENABLED | With true, each application token authorizes with its own permissions. The hub then answers 401 to a token whose type claim is not normal-user or application. Without true, every token that is not a user token authorizes under one shared role. | false | No |
AUTH_M2M_PRODUCT_FORWARD_ENABLED | With true and AUTH_M2M_INVERSION_ENABLED=true, the hub also sends its product name to Access Manager when it checks an application token. | false | No |
AUTH_TIMEOUT | Time limit for the Access Manager check of one request, retries included. | 30s | No |
AUTH_CACHE_TTL | Time that the hub keeps each Access Manager decision. A permission change can take this long to apply. When unset, the hub keeps no decisions. | — | No |
AUTH_BREAKER_ENABLED | Turns on a circuit breaker for Access Manager calls. After 5 failed calls in a row, it stops the calls for 30 seconds. Meanwhile, the hub refuses each request that has no cached approval. | false | No |
AUTH_RETRY_MAX | Maximum retries of an Access Manager call that fails without a decision. 0 turns off retries. | 0 | No |
AUTH_JWT_VERIFY_CERT | One or more PEM RSA public keys or X.509 certificates, separated by newlines. With a loaded key, the hub checks the RS256 signature and the expiry of each bearer token, and answers 401 when the check fails. It takes precedence over AUTH_JWT_VERIFY_CERT_PATH. | — | No |
AUTH_JWT_VERIFY_CERT_PATH | Path to a file with the same content. The hub reads it only when AUTH_JWT_VERIFY_CERT is empty. | — | No |
AUTH_JWT_ISSUER | With a loaded key, the hub answers 401 to a token whose iss claim differs from this value. | — | No |
TRUSTED_PROXIES | Comma-separated CIDR ranges of the proxies that connect directly to the hub. The hub resolves the caller’s address through them and sends it to Access Manager for the IP allowlist. When unset, the hub sends no caller address. | — | No |
IDP_DECLARATION_ENABLED | Publishes the hub’s permission declaration to the identity service at startup. Only true turns it on. The publication also needs PLUGIN_AUTH_ENABLED=true set in the environment. It also needs the Access Manager address set in the environment as PLUGIN_AUTH_HOST, or as PLUGIN_AUTH_ADDRESS when PLUGIN_AUTH_HOST is empty. When it fails, the hub logs a warning and keeps serving. | — | No |
IDP_HOST | Identity service base URL for the declaration. | — | With the declaration on |
IDP_M2M_CLIENT_ID | Client ID for the declaration. | — | With the declaration on |
IDP_M2M_CLIENT_SECRET | Client secret for the declaration. Sensitive. | — | With the declaration on |
Multi-tenant mode
| Variable | Description | Default | Required |
|---|---|---|---|
MULTI_TENANT_ENABLED | Turns on multi-tenant mode through Tenant Manager. | false | No |
ENV_NAME | Environment name for Tenant Manager. Multi-tenant mode refuses an empty value and local. | — | Multi-tenant mode |
MULTI_TENANT_URL | Tenant Manager URL. | — | Multi-tenant mode |
MULTI_TENANT_SERVICE_API_KEY | API key that the hub sends to Tenant Manager. Sensitive. | — | Multi-tenant mode |
MULTI_TENANT_ALLOW_INSECURE_HTTP | Allows an http Tenant Manager URL. | false | No |
MULTI_TENANT_TIMEOUT | Timeout, in seconds, for a Tenant Manager call. 0 uses the library default. | 0 | No |
MULTI_TENANT_CACHE_TTL_SEC | Seconds the hub caches a tenant’s configuration. 0 uses the library default. | 0 | No |
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD | Failed Tenant Manager calls before the circuit breaker opens. 0 turns off the breaker. | 0 | No |
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC | Seconds the circuit breaker stays open. 0 uses the library default. | 0 | No |
MULTI_TENANT_REDIS_HOST | Redis host that carries tenant lifecycle events. When empty, the hub runs without that listener. | — | No |
MULTI_TENANT_REDIS_PORT | Port of that Redis. | 6379 | No |
MULTI_TENANT_REDIS_PASSWORD | Password for that Redis. Sensitive. | — | No |
MULTI_TENANT_REDIS_TLS | Uses TLS for that Redis. | false | No |
MULTI_TENANT_REDIS_CA_CERT | CA certificate for that TLS connection. | — | No |
AWS_REGION | AWS region, read by the AWS SDK. | — | No |
AWS setup artifacts
| Variable | Description | Default | Required |
|---|---|---|---|
STREAMING_HUB_AWS_HUB_PRINCIPAL_ARN | ARN of the hub’s AWS role. Your delegated-grant role trusts it, and the setup artifacts put it in the trust policy. When empty, the hub generates no AWS setup artifacts. | — | No |
STREAMING_HUB_AWS_SETUP_TEMPLATE_URL | Public URL of the CloudFormation template that creates the delegated-grant role. When empty, the hub generates no AWS setup artifacts. | — | No |