Open-source core

Getting started

Install the open-source Lurcast server, give it a minimal configuration, send it a stream and listen.

This page covers the open-source core, licensed under the GNU AGPL-3.0. Its source code is on GitHub. If you bought the Hosting edition, read Install the Hosting edition instead; the steps below about configuration and encoders still apply.

Download a binary#

Each release has static Linux binaries: lurcast-linux-amd64 for x86-64 and lurcast-linux-arm64 for ARM64. They need nothing else installed.

curl -fLo lurcast https://github.com/lurcast/lurcast/releases/latest/download/lurcast-linux-amd64
chmod +x lurcast
./lurcast --version
./lurcast --config config.yml

On an ARM64 machine, download lurcast-linux-arm64 instead.

--config (or -c) defaults to config.yml in the current directory. If the file does not exist, Lurcast starts with the built-in defaults.

Run with Docker#

The image ghcr.io/lurcast/lurcast runs the server as an unprivileged user. Tags: latest, an exact version such as 0.1.0, or a minor version such as 0.1.

Configure it with environment variables:

docker run -d --name lurcast -p 8000:8000 \
  -e LURCAST_SOURCE_PASSWORD=change-me-source \
  -e LURCAST_ADMIN_PASSWORD=change-me-admin \
  -e LURCAST_RELAY_PASSWORD=change-me-relay \
  ghcr.io/lurcast/lurcast:0.1

Or mount a config file at /etc/lurcast/config.yml:

docker run -d --name lurcast -p 8000:8000 \
  -v "$PWD/config.yml:/etc/lurcast/config.yml:ro" \
  ghcr.io/lurcast/lurcast:0.1

Run with systemd#

The repository ships a hardened unit, deploy/lurcast.service. It runs /usr/local/bin/lurcast --config /etc/lurcast/config.yml as the lurcast user.

sudo install -m 0755 lurcast /usr/local/bin/lurcast
sudo useradd --system --no-create-home --shell /usr/sbin/nologin lurcast
sudo mkdir -p /etc/lurcast
sudo cp config.yml /etc/lurcast/config.yml
sudo curl -fLo /etc/systemd/system/lurcast.service \
  https://github.com/lurcast/lurcast/raw/HEAD/deploy/lurcast.service
sudo systemctl daemon-reload
sudo systemctl enable --now lurcast

The unit sets LimitNOFILE=65536. Each listener holds one socket, so keep the open file limit above max_listeners. The unit makes /etc/lurcast read-only; if your fallback or intro files live elsewhere, add that directory to the unit. To bind a port below 1024 without root, uncomment AmbientCapabilities=CAP_NET_BIND_SERVICE.

Build from source#

You need Crystal 1.21.0 or newer and libogg.

# macOS
brew install libogg

# Debian or Ubuntu
sudo apt install libogg-dev

Clone the repository, then build a release binary and start it:

git clone https://github.com/lurcast/lurcast.git
cd lurcast
shards build --release
./bin/lurcast --config config.yml

To build your own Docker image instead, run docker build -t lurcast . in the repository. Its Dockerfile builds a static binary on Alpine.

A minimal configuration#

host: 0.0.0.0
port: 8000
hostname: radio.example
public_url: http://radio.example:8000

admin_password: "change-me-admin"
source_password: "change-me-source"
relay_password: "change-me-relay"

Change admin_password, source_password and relay_password before you expose the server. All three default to hackme, and Lurcast logs a warning at startup for any still set to it.

Every other setting has a default. See the configuration reference for the full list, including TLS, mounts, fallbacks and relays.

Connect an encoder#

Point any Icecast-compatible encoder at the server:

Setting Value
Server type Icecast (HTTP PUT or legacy SOURCE)
Host and port radio.example, 8000
Mount Any path, for example /radio.mp3
Username source
Password Your source_password

The mount is created when the source connects. To try it with ffmpeg, sending MP3 without transcoding:

ffmpeg -re -i song.mp3 -c copy -content_type audio/mpeg -f mp3 \
  icecast://source:change-me-source@radio.example:8000/radio.mp3

Or Ogg Opus:

ffmpeg -re -i song.mp3 -c:a libopus -content_type audio/ogg -f ogg \
  icecast://source:change-me-source@radio.example:8000/radio.ogg

SHOUTcast v1 and v2 encoders need a dedicated source port. See Encoders and compatibility.

Lurcast relays encoded audio as it arrives. It does not transcode, so send the format and bitrate your listeners should get.

Listen#

Open the mount URL in a player or browser:

http://radio.example:8000/radio.mp3

Add .m3u to a mount for a playlist file (/radio.mp3.m3u). The status page at / lists the active mounts with a player, and GET /api/v1/stations returns them as JSON. Sign in to the admin dashboard at /admin/ with your admin_password to watch listeners and manage mounts.

Next steps#