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#
- Set per-mount limits, fallbacks and relays in the configuration reference.
- Connect SHOUTcast encoders, admin tools and directory listings: Encoders and compatibility.