Configuration reference

Encore reads its configuration from these sources, later ones winning:

1. Built-in defaults (listed below).
2. A YAML file: --config <path> (or ENCORE_CONFIG), otherwise encore.yml in the data directory when it exists. In the container that is /config/encore.yml.
3. Environment variables: ENCORE_ followed by the key in upper case, with its dots as underscores, e.g. server.address is ENCORE_SERVER_ADDRESS and server.trusted_proxies is ENCORE_SERVER_TRUSTED_PROXIES. Each setting below lists its variable. Lists take comma-separated values.
4. Command-line flags that were explicitly set (see the CLI reference).

Any environment variable ending in _FILE reads the value of the variable without the suffix from that file, for Docker and Kubernetes secrets: ENCORE_STORAGE_S3_SECRET_KEY_FILE=/run/secrets/s3_secret_key sets storage.s3.secret_key.

Most settings can also be changed in the web interface. Keys set in the config file, the environment or flags are shown there as managed by config and can’t be changed from the web interface until you remove them.

Lists of objects (kodi, rooms, devices) can only be set in the config file.

server

server configures the single HTTP listener.

server.address

• Type: string
• Default: ":8080"
• Environment: ENCORE_SERVER_ADDRESS

server.address is the listen address, e.g. “:8080”.

server.base_path

• Type: string
• Default: "/"
• Environment: ENCORE_SERVER_BASE_PATH

server.base_path is the URL path prefix when served behind a path-routing proxy, e.g. /encore. Encore also keeps answering at /, so the proxy may forward with or without the prefix and a wrong value never locks you out. It can’t start with one of Encore’s own routes (/api, /kodi, /settings, …). It can also be changed under Settings › General, which applies it straight away.

server.trusted_proxies

• Type: list of strings
• Default: [127.0.0.1/32, ::1/128]
• Environment: ENCORE_SERVER_TRUSTED_PROXIES

server.trusted_proxies lists the CIDRs whose X-Forwarded-* and auth headers are honoured. Headers from anywhere else are ignored.

log

log configures structured logging.

log.level

• Type: string
• Default: "info"
• Environment: ENCORE_LOG_LEVEL

log.level is debug, info, warn or error. It can also be changed under Settings › General, which applies it without a restart.

log.format

• Type: string
• Default: "auto"
• Environment: ENCORE_LOG_FORMAT

log.format is auto, pretty, text or json. pretty is coloured for a terminal (honouring NO_COLOR), text is logfmt key=value lines, json is one object per line; auto is pretty on a terminal and text otherwise.

data_dir

• Type: string
• Default: per user: $XDG_DATA_HOME/encore (normally ~/.local/share/encore) on Linux and other Unix systems, ~/Library/Application Support/encore on macOS, %LocalAppData%\encore on Windows; the container image and the systemd unit set their own
• Environment: ENCORE_DATA_DIR

data_dir holds the database, the generated secrets key, local storage and encore.yml. It defaults to a per-user directory; the container image sets it to /config and the systemd unit to /var/lib/encore.

alexa

alexa configures the custom skill endpoint.

alexa.skill_id

• Type: string
• Default: ""
• Environment: ENCORE_ALEXA_SKILL_ID

alexa.skill_id is the skill’s application ID; requests for any other skill are rejected. It is normally set by the deploy flow rather than by hand.

alexa.locales

• Type: list of strings
• Default: []
• Environment: ENCORE_ALEXA_LOCALES

alexa.locales limits which locales are built and deployed, e.g. [“en-AU”]. Empty means every locale Encore ships. An Echo can only use the skill when its language matches a deployed locale; fewer locales deploy faster.

alexa.content

• Type: list of strings
• Default: [movies, tv, music]
• Environment: ENCORE_ALEXA_CONTENT

alexa.content lists what the skill can play: movies, tv and music (music includes music videos). Leaving a group out leaves its intents out of the skill model and its titles out of “play X” searches, and library syncs no longer fetch it from Kodi. The setup wizard asks before the first Kodi is added.

alexa.shutdown_quits

• Type: bool
• Default: false
• Environment: ENCORE_ALEXA_SHUTDOWN_QUITS

alexa.shutdown_quits makes “shut down” quit Kodi rather than power off the machine, for Kodi running on a desktop. A Kodi instance can override it.

alexa.confirm_sound

• Type: bool
• Default: true
• Environment: ENCORE_ALEXA_CONFIRM_SOUND

alexa.confirm_sound plays a short sound after a command that has nothing to say, such as pause or volume up, so Alexa doesn’t answer with silence.

alexa.deep_search

• Type: bool
• Default: true
• Environment: ENCORE_ALEXA_DEEP_SEARCH

alexa.deep_search makes “play X” search music as well as films and TV when the request doesn’t say which (Kanzi’s deep_search).

alexa.queue_limit

• Type: integer
• Default: 100
• Environment: ENCORE_ALEXA_QUEUE_LIMIT

alexa.queue_limit caps how many items a shuffle or queue plays at once (Kanzi’s playlist_max_items), which keeps large libraries responsive. It can also be changed under Settings › Features.

storage

storage configures where snapshots, exports and database backups are written. The SQLite database itself always lives in data_dir.

storage.backend

• Type: string
• Default: "local"
• Environment: ENCORE_STORAGE_BACKEND

storage.backend is local, s3 or webdav.

storage.local.path

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_LOCAL_PATH

storage.local.path is the root directory; empty means data_dir/blobs.

storage.s3.endpoint

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_ENDPOINT

storage.s3.endpoint is the service URL, e.g. https://s3.eu-west-1.amazonaws.com or http://minio:9000.

storage.s3.region

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_REGION

storage.s3.region is the signing region; empty lets the client discover it.

storage.s3.bucket

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_BUCKET

storage.s3.bucket must already exist.

storage.s3.prefix

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_PREFIX

storage.s3.prefix is prepended to every object key.

storage.s3.addressing

• Type: string
• Default: "auto"
• Environment: ENCORE_STORAGE_S3_ADDRESSING

storage.s3.addressing is auto, path (http://host/bucket/key) or virtual (http://bucket.host/key). Most self-hosted servers need path.

storage.s3.access_key

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_ACCESS_KEY

storage.s3.access_key is the access key ID.

storage.s3.secret_key

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_SECRET_KEY

storage.s3.secret_key is best supplied with ENCORE_STORAGE_S3_SECRET_KEY_FILE.

storage.s3.ca_bundle

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_CA_BUNDLE

storage.s3.ca_bundle is a PEM file of extra CAs trusted in addition to the system pool.

storage.s3.insecure_skip_verify

• Type: bool
• Default: false
• Environment: ENCORE_STORAGE_S3_INSECURE_SKIP_VERIFY

storage.s3.insecure_skip_verify disables TLS certificate checks. For labs only.

storage.s3.sse

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_SSE

storage.s3.sse requests server-side encryption: empty for none, s3 (SSE-S3) or kms (SSE-KMS with storage.s3.sse_kms_key_id).

storage.s3.sse_kms_key_id

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_S3_SSE_KMS_KEY_ID

storage.s3.sse_kms_key_id is the KMS key used when SSE is kms.

storage.webdav.url

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_WEBDAV_URL

storage.webdav.url is the collection to write under, e.g. https://cloud.example.com/remote.php/dav/files/backup/encore.

storage.webdav.username

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_WEBDAV_USERNAME

storage.webdav.username is the WebDAV account name.

storage.webdav.password

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_WEBDAV_PASSWORD

storage.webdav.password is best set to an app password rather than the account password.

storage.webdav.prefix

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_WEBDAV_PREFIX

storage.webdav.prefix is prepended to every object path below URL.

storage.webdav.ca_bundle

• Type: string
• Default: ""
• Environment: ENCORE_STORAGE_WEBDAV_CA_BUNDLE

storage.webdav.ca_bundle is a PEM file of extra CAs trusted in addition to the system pool.

storage.webdav.insecure_skip_verify

• Type: bool
• Default: false
• Environment: ENCORE_STORAGE_WEBDAV_INSECURE_SKIP_VERIFY

storage.webdav.insecure_skip_verify disables TLS certificate checks. For labs only.

storage.backups.schedule

• Type: string
• Default: "daily@03:00"
• Environment: ENCORE_STORAGE_BACKUPS_SCHEDULE

storage.backups.schedule is off, hourly, daily@HH:MM, weekly@DAY@HH:MM or every@DURATION (at least 1m), with times in the server’s local time zone.

storage.backups.keep

• Type: integer
• Default: 14
• Environment: ENCORE_STORAGE_BACKUPS_KEEP

storage.backups.keep is how many backups to retain.

storage.backups.prefix

• Type: string
• Default: "Encore"
• Environment: ENCORE_STORAGE_BACKUPS_PREFIX

storage.backups.prefix is the folder backups are written to, below the backend’s own prefix. Empty puts them at the top.

secrets

secrets configures encryption of secrets at rest. With neither field set a key is generated into data_dir.

secrets.key

• Type: string
• Default: ""
• Environment: ENCORE_SECRETS_KEY

secrets.key is a base64-encoded 32-byte key. ENCORE_SECRETS_KEY_FILE fills it from a file.

secrets.key_file

• Type: string
• Default: ""
• Environment: config file only

secrets.key_file names a file holding the base64-encoded key. It can only be set in the config file, because the environment variable of that name is the _FILE form of Key.

auth

auth configures how admins sign in to the web interface. Anything left unset here can be changed in the web interface instead; values set here are shown there as managed by config.

auth.mode

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_MODE

auth.mode is local (a username and password stored by Encore), oidc (an OpenID Connect provider) or header (a trusted reverse proxy’s Remote-User header). Empty leaves the choice to the web interface, which starts in local mode.

auth.break_glass

• Type: bool
• Default: false
• Environment: ENCORE_AUTH_BREAK_GLASS or ENCORE_BREAK_GLASS

auth.break_glass keeps local sign-in working while oidc or header mode is active, as a way in when the provider or proxy is broken. It can be turned on under Settings › Access; if you’re already locked out, set ENCORE_BREAK_GLASS=true and remove it afterwards.

auth.session_hours

• Type: integer
• Default: 168
• Environment: ENCORE_AUTH_SESSION_HOURS

auth.session_hours is how long an idle session lasts; activity extends it.

auth.lockout_attempts

• Type: integer
• Default: 5
• Environment: ENCORE_AUTH_LOCKOUT_ATTEMPTS

auth.lockout_attempts failed sign-ins within auth.lockout_minutes lock the account for auth.lockout_minutes.

auth.lockout_minutes

• Type: integer
• Default: 15
• Environment: ENCORE_AUTH_LOCKOUT_MINUTES

auth.lockout_minutes is both the window failed sign-ins are counted in and how long the lockout lasts.

auth.oidc.issuer

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_OIDC_ISSUER

auth.oidc.issuer is the provider’s issuer URL; its /.well-known/openid-configuration must be reachable from Encore.

auth.oidc.client_id

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_OIDC_CLIENT_ID

auth.oidc.client_id is the client registered for Encore at the provider.

auth.oidc.client_secret

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_OIDC_CLIENT_SECRET

auth.oidc.client_secret is best supplied with ENCORE_AUTH_OIDC_CLIENT_SECRET_FILE.

auth.oidc.scopes

• Type: list of strings
• Default: [openid, profile, email, groups]
• Environment: ENCORE_AUTH_OIDC_SCOPES

auth.oidc.scopes are requested at sign-in; include the one that adds auth.oidc.groups_claim to the ID token when auth.oidc.admin_group is set.

auth.oidc.admin_group

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_OIDC_ADMIN_GROUP

auth.oidc.admin_group, when set, must appear in the auth.oidc.groups_claim of the ID token. When empty, anyone the provider lets sign in is an admin.

auth.oidc.groups_claim

• Type: string
• Default: "groups"
• Environment: ENCORE_AUTH_OIDC_GROUPS_CLAIM

auth.oidc.groups_claim is the ID token claim that lists the user’s groups.

auth.oidc.redirect_uri

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_OIDC_REDIRECT_URI

auth.oidc.redirect_uri overrides the callback URL derived from the request, e.g. https://encore.example.net/api/v1/auth/oidc/callback.

auth.header.user_header

• Type: string
• Default: "Remote-User"
• Environment: ENCORE_AUTH_HEADER_USER_HEADER

auth.header.user_header carries the signed-in user’s name.

auth.header.groups_header

• Type: string
• Default: "Remote-Groups"
• Environment: ENCORE_AUTH_HEADER_GROUPS_HEADER

auth.header.groups_header carries the user’s groups, comma-separated.

auth.header.admin_group

• Type: string
• Default: ""
• Environment: ENCORE_AUTH_HEADER_ADMIN_GROUP

auth.header.admin_group, when set, must be one of the comma-separated groups in auth.header.groups_header.

kodi

kodi declares Kodi instances as code; most installs add them in the web UI instead. kodi[] declares a Kodi host in the config file. Instances declared here are created or updated in the database at startup and shown as managed by config in the web UI; instances added in the UI live only in the database.

kodi[].name

• Type: string
• Environment: config file only

kodi[].name identifies the instance, e.g. “Lounge”. It must be unique.

kodi[].url

• Type: string
• Environment: config file only

kodi[].url is the HTTP JSON-RPC endpoint, e.g. http://192.168.1.20:8080/jsonrpc.

kodi[].websocket_url

• Type: string
• Environment: config file only

kodi[].websocket_url is the JSON-RPC WebSocket for live updates, e.g. ws://192.168.1.20:9090/jsonrpc. Empty disables live updates.

kodi[].username

• Type: string
• Environment: config file only

kodi[].username is Kodi’s web server user name; when empty, the user in URL is used.

kodi[].password

• Type: string
• Environment: config file only

kodi[].password is Kodi’s web server password; when empty, the password in URL is used.

kodi[].mac

• Type: string
• Environment: config file only

kodi[].mac enables Wake-on-LAN. Encore also learns it from Kodi once connected.

kodi[].broadcast

• Type: string
• Environment: config file only

kodi[].broadcast is where Wake-on-LAN packets are sent, “host” or “host:port”; empty means 255.255.255.255:9.

kodi[].default

• Type: bool
• Environment: config file only

kodi[].default makes this instance answer Echo devices that aren’t linked to one.

kodi[].language

• Type: string
• Environment: config file only

kodi[].language selects title-matching rules for this library: en, de, es, fr or it. Defaults to en.

kodi[].library_group

• Type: string
• Environment: config file only

kodi[].library_group names the shared library database this instance reads (MySQL/MariaDB). Instances with the same name share one library catalog and title index. “none” forces the instance to keep its own; empty lets Encore detect sharing.

kodi[].shutdown_quits

• Type: bool
• Environment: config file only

kodi[].shutdown_quits overrides alexa.shutdown_quits for this instance when set.

kodi[].timezone

• Type: string
• Environment: config file only

kodi[].timezone is the Kodi host’s IANA time zone (e.g. “Australia/Melbourne”), which Kodi writes library dates in. Empty means learn the UTC offset from Kodi’s clock.

rooms

rooms declares rooms as code, mainly for stateless deployments. rooms[] declares a room in the config file: where an Echo is, and the spoken names for “…in the lounge”.

rooms[].name

• Type: string
• Environment: config file only

rooms[].name is the room’s name, which is also a spoken name for it.

rooms[].kodi

• Type: string
• Environment: config file only

rooms[].kodi is the name of the Kodi instance that plays in this room.

rooms[].aliases

• Type: list of strings
• Environment: config file only

rooms[].aliases are other spoken names for the room, e.g. “living room” for the lounge.

devices

devices declares Echo links as code, mainly for stateless deployments. devices[] declares an Echo in the config file, linking it to a Kodi instance (and optionally a room) without the web interface.

devices[].id

• Type: string
• Environment: config file only

devices[].id is the Alexa device ID (amzn1.ask.device.…), shown in the request log for new Echos.

devices[].name

• Type: string
• Environment: config file only

devices[].name is shown in the web interface and the request log.

devices[].kodi

• Type: string
• Environment: config file only

devices[].kodi is the name of the Kodi instance this Echo controls.

devices[].room

• Type: string
• Environment: config file only

devices[].room is the name of the room the Echo is in.

stateless

• Type: bool
• Default: false
• Environment: ENCORE_STATELESS

stateless runs without a persistent data directory: the database is restored from the storage backend at startup and saved back as it changes, like Kanzi’s cloud deployments.