Configuration

Key Behaviors to Know First

These rules affect how everything behaves at runtime:

Environment variables always win. They override any YAML value regardless of which file it came from.
Replay and watch behavior is controlled by request parameters, not static config switches.
Invalid policy values fail startup immediately. storage_type, retention_policy, and discard_policy are parsed as typed enums; bad values are caught before any streams are created.
Per-schema storage_policy is validated at startup against the selected backend’s capabilities. Unsupported fields (for example retention_time on in_memory) cause a startup failure with a clear error.
JetStream stream changes require a restart or rollout. Aviso uses the configuration loaded at startup. After loading the updated config, it reconciles existing streams when accessed, not through an all-stream sweep. Compression affects future file-storage writes, not an automatic rewrite of history. Deleting and recreating a stream loses its stored messages.
/api/v1/schema responses are client-focused. Internal storage_policy settings are not exposed.

Loading Precedence

Configuration is loaded in this order (later sources override earlier ones):

./configuration/config.yaml
/etc/aviso_server/config.yaml
$HOME/.aviso_server/config.yaml
Environment variables (highest precedence)

If AVISOSERVER_CONFIG_FILE is set, only that single file is loaded (steps 1 through 3 are skipped). Environment variables still override values from the file.

Environment variable format

Prefix: AVISOSERVER_ Nested separator: __

AVISOSERVER_APPLICATION__HOST=0.0.0.0
AVISOSERVER_APPLICATION__PORT=8000
AVISOSERVER_NOTIFICATION_BACKEND__KIND=jetstream
AVISOSERVER_NOTIFICATION_BACKEND__JETSTREAM__NATS_URL=nats://localhost:4222

Config File Structure

The top-level sections are:

Section	Purpose
`application`	Server host, port, static files path
`logging`	Log level and format
`auth`	Authentication mode, secrets, admin roles
`notification_backend`	Backend selection and backend-specific settings
`notification_schema`	Per-event-type validation, topic ordering, storage policy
`metrics`	Optional Prometheus metrics server
`watch_endpoint`	SSE heartbeat, connection limits, replay batch settings

notification_backend.kind selects the storage implementation:

jetstream: production backend (NATS JetStream).
in_memory: development backend (process-local, no persistence).

Backend Details

Backends Overview: choose the right backend.
In-Memory Backend: behavior and caveats.
JetStream Backend: setup, stream management, operational notes.
Kubernetes deployment: Helm chart.

For full field-level documentation of every config option, see Configuration Reference.