The stack is configured with environment variables in .env, next to docker-compose.yml. Start from .env.example. Station settings (crossfade, rotation, time zone, library layout, AcoustID key…) are not here: they are stored in the database and changed from the web interface or the API.
| Variable |
Default |
Meaning |
HERON_VERSION |
latest |
Image tag of the five services: latest, edge, or a release such as 0.1.0. See Upgrading |
| Variable |
Default |
Meaning |
HERON_DB_PASSWORD |
change-me |
MariaDB password of Heron’s user. Use letters, digits, - and _: it is embedded in a URL |
HERON_DB_ROOT_PASSWORD |
change-me-too |
MariaDB root password |
| Variable |
Default |
Meaning |
HERON_MUSIC_DIR |
./data/music |
The music library |
HERON_FALLBACK_DIR |
./data/fallback |
Tracks the engine plays when its queue runs dry |
HERON_INCOMING_FOLDER |
./data/incoming |
Drop new files here: they move into the buffer zone |
HERON_STAGING_FOLDER |
./data/staging |
The buffer zone: new files waiting to be imported. Best on the library’s file system |
HERON_LIBRARIAN_USER |
1000:1000 |
uid:gid that heron-librarian and heron-api run as: the owner of the music, incoming and buffer folders |
| Variable |
Default |
Meaning |
HERON_SCAN_INTERVAL |
3600 |
Seconds between full library scans |
HERON_LIBRARY_WATCH |
true |
Scan when files change. Set false on network shares that do not report changes |
HERON_NICE |
10 |
Niceness of heron-analyzer and heron-librarian (0 to 19), so they yield the CPU and disk to the engine |
| Variable |
Default |
Meaning |
HERON_HTTP_PORT |
8000 |
Host port of the web interface and the API |
HERON_ICECAST_PORT |
8010 |
Host port of the optional local Icecast server (--profile icecast) |
| Variable |
Default |
Meaning |
RUST_LOG |
info |
Log level of the services, for example heron_engine=debug,info |
HERON_SENTRY_DSN |
empty: off |
Sentry DSN for the services’ errors |
HERON_WEB_SENTRY_DSN |
empty: off |
Sentry DSN for the web interface. Browsers read it: give it a project of its own |
HERON_SENTRY_ENVIRONMENT |
production |
Sentry environment |
| Variable |
Default |
Meaning |
HERON_STATION_NAME |
heron |
The station label of every metric |
HERON_METRICS_REMOTE_WRITE_URL |
empty: off |
Prometheus remote write endpoint |
HERON_METRICS_REMOTE_WRITE_USERNAME |
|
Basic auth user (Grafana Cloud: the instance ID). Empty: the password is sent as a bearer token |
HERON_METRICS_REMOTE_WRITE_PASSWORD |
|
Basic auth password or bearer token |
HERON_METRICS_REMOTE_WRITE_INTERVAL |
15 |
Seconds between pushes |
See Monitoring.
HTTPS is left to a reverse proxy in front of heron-web (Caddy, nginx, Traefik…). Have the proxy set X-Forwarded-Proto, so session cookies are marked Secure. The proxy must also forward WebSocket connections on /api/v1/live.
The services’ own ports (metrics and health checks) have no authentication: never publish them on the Internet.
