Skip to content
Heron Broadcaster

Installation

Heron runs as a Docker Compose stack on Linux, on amd64 or arm64 (a Raspberry Pi 4 or 5 is enough for a small station).

Requirements

Section titled “Requirements”
  • Docker with Compose v2
  • A folder of music (MP3, AAC or ALAC in M4A, FLAC, Ogg Vorbis, WAV or AIFF)
  • Optionally, an Icecast server to stream to. The stack can start a local one for testing.

1. Get the Compose files

Section titled “1. Get the Compose files”

Clone the repository, or download docker-compose.yml and .env.example from it:

Terminal window
git clone https://github.com/dehy/heron-broadcaster.git
cd heron-broadcaster

2. Configure

Section titled “2. Configure”

Copy the example environment file and change the passwords:

Terminal window
cp .env.example .env

At least set:

Variable What to put
HERON_DB_PASSWORD, HERON_DB_ROOT_PASSWORD Database passwords: letters, digits, - and _ only
HERON_MUSIC_DIR Your music folder (default ./data/music)
HERON_LIBRARIAN_USER The owner of your music, as uid:gid: the output of id -u and id -g

Then create the folders Heron uses, or point the variables elsewhere:

Terminal window
mkdir -p data/music data/fallback data/incoming data/staging

Every variable is described in Configuration.

3. Start the stack

Section titled “3. Start the stack”
Terminal window
docker compose up -d --wait

Compose pulls the images from ghcr.io/dehy and waits until every service is healthy. Database migrations run automatically when heron-api starts.

4. Create the first admin

Section titled “4. Create the first admin”
Terminal window
docker compose exec heron-api heron-api user add admin --role admin

The command asks for a password (8 characters or more).

5. Sign in

Section titled “5. Sign in”

Open http://localhost:8000 (or your server’s address, on HERON_HTTP_PORT) and sign in.

Heron starts scanning HERON_MUSIC_DIR right away. The Tracks page shows the tracks as they are analyzed. Next: First steps.

Add fallback tracks

Section titled “Add fallback tracks”

Put a few tracks that suit any hour (station IDs, evergreen music) in HERON_FALLBACK_DIR (./data/fallback). The engine plays them when its queue runs dry, for example while the API is down.

Building from source

Section titled “Building from source”

The images are built for amd64 and arm64 and published once the whole stack has passed its tests on both. To build them yourself instead, add --build:

Terminal window
docker compose up -d --build --wait