Hosting edition

Install the Hosting edition

Download the Hosting edition binary with your license key, run it with Docker or systemd, and configure the hosting section.

The Hosting edition is the Lurcast server plus a provisioning API, usage metering, plan limits, Prometheus metrics and royalty reports. It runs every customer station in one process. Everything in the configuration reference still applies; the Hosting edition adds a hosting: section.

It needs a license key. You get one by email after each payment, or from info@lurcast.com for a 30-day trial. See Licensing and renewal.

Download#

The Hosting edition ships as one static Linux x86-64 binary. Save your key as license.key, then download the binary with it:

curl -fL -H "Authorization: Bearer $(cat license.key)" \
  -o lurcast-hosting \
  https://lurcast.com/api/download/lurcast-hosting/linux-amd64
chmod +x lurcast-hosting
./lurcast-hosting --version

The binary has no runtime dependencies. To upgrade, download it again, replace the old file and restart the service.

Configure#

Start from a normal Lurcast configuration and add a hosting: section. A typical file:

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

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

max_sources: 1000          # one per live station
max_listeners: 20000
data_dir: /var/lib/lurcast # bans and listener history

hosting:
  api_token: "replace-with-at-least-24-random-characters"
  data_dir: /var/lib/lurcast
  license_file: /var/lib/lurcast/license.key
  license_url: https://lurcast.com/api/license/renew
  meter_interval: 5
  allow_unprovisioned_mounts: false
  anonymize_ips: true
  geoip_database: /var/lib/lurcast/dbip-country-lite.mmdb

Generate the API token with, for example, openssl rand -hex 32.

Setting Default Environment variable Notes
api_token none LURCAST_HOSTING_API_TOKEN Bearer token for the API and /metrics. At least 24 characters; the server will not start without it.
data_dir data LURCAST_HOSTING_DATA_DIR Stations, usage and report files. Must be writable.
license_file license.key LURCAST_HOSTING_LICENSE_FILE Your license key. Its directory must be writable for automatic renewal.
license_url https://lurcast.com/api/license/renew LURCAST_HOSTING_LICENSE_URL Where the key is renewed. "" turns automatic renewal off.
meter_interval 5 file only Seconds between usage samples and limit checks.
allow_unprovisioned_mounts false file only Allow sources on mounts that are not provisioned stations, using the global source_password.
anonymize_ips true file only Store listener addresses in session reports truncated (IPv4 to /24, IPv6 to /48).
geoip_database none LURCAST_HOSTING_GEOIP_DATABASE Country database (.mmdb) for listener locations.

The top-level data_dir is the core server's own (bans and listener history); hosting.data_dir holds the Hosting edition's files. They can be the same directory.

Relative paths are resolved from the directory the server starts in, so use absolute paths in production.

Raise max_sources to at least the number of stations that can be live at once. The server logs a warning when there are more stations than max_sources. max_listeners is still the limit for the whole server; each station's own limit is set through the API.

With allow_unprovisioned_mounts: false, a source can only connect to a station you created through the API, with that station's username and password.

Run with systemd#

Install the binary and create a user and data directory:

sudo install -m 0755 lurcast-hosting /usr/local/bin/lurcast-hosting
sudo useradd --system --no-create-home --shell /usr/sbin/nologin lurcast
sudo mkdir -p /etc/lurcast /var/lib/lurcast
sudo install -m 0640 -g lurcast config.yml /etc/lurcast/config.yml
sudo install -m 0600 -o lurcast -g lurcast license.key /var/lib/lurcast/license.key
sudo chown lurcast:lurcast /var/lib/lurcast

Save this unit as /etc/systemd/system/lurcast-hosting.service:

[Unit]
Description=Lurcast streaming server (Hosting edition)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=lurcast
Group=lurcast
ExecStart=/usr/local/bin/lurcast-hosting --config /etc/lurcast/config.yml
Restart=on-failure
RestartSec=2
# Each listener holds one socket; raise this above max_listeners.
LimitNOFILE=65536

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
# Uncomment to bind ports below 1024 without root.
# AmbientCapabilities=CAP_NET_BIND_SERVICE
ReadOnlyPaths=/etc/lurcast
# Stations, usage, reports and the renewed license key are written here.
ReadWritePaths=/var/lib/lurcast

[Install]
WantedBy=multi-user.target

Then start it:

sudo systemctl daemon-reload
sudo systemctl enable --now lurcast-hosting
journalctl -u lurcast-hosting -f

Run with Docker#

Build a small image around the binary. Put this Dockerfile next to lurcast-hosting:

FROM alpine:3.22
RUN apk add --no-cache ca-certificates \
    && addgroup -S -g 10001 lurcast \
    && adduser -S -u 10001 -G lurcast -H lurcast \
    && mkdir -p /etc/lurcast /var/lib/lurcast \
    && chown lurcast:lurcast /var/lib/lurcast
COPY lurcast-hosting /usr/local/bin/lurcast-hosting
USER lurcast
EXPOSE 8000
ENTRYPOINT ["/usr/local/bin/lurcast-hosting"]
CMD ["--config", "/etc/lurcast/config.yml"]

ca-certificates lets the server reach HTTPS endpoints such as license_url and relay upstreams.

Keep the data directory, including the license key, on the host so it survives new containers:

docker build -t lurcast-hosting .

sudo mkdir -p /srv/lurcast/data
sudo cp license.key /srv/lurcast/data/license.key
sudo chown -R 10001:10001 /srv/lurcast/data

docker run -d --name lurcast --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  -p 8000:8000 \
  -v /srv/lurcast/config.yml:/etc/lurcast/config.yml:ro \
  -v /srv/lurcast/data:/var/lib/lurcast \
  lurcast-hosting

This assumes data_dir: /var/lib/lurcast and license_file: /var/lib/lurcast/license.key in the config. Publish any other ports you use, such as tls_port or shoutcast_port.

Check that it runs#

At startup the server logs who the license belongs to, when it expires and how many stations it has. If the key is missing or not valid, it logs why and exits.

Ask the API for the license:

curl -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/license
{
  "licensee": "Example Hosting AB",
  "expires_at": "2026-12-16T00:00:00Z",
  "expired": false,
  "lapsed": false,
  "max_stations": 100,
  "stations": 0
}

Then create your first station with the provisioning API, or connect WHMCS.

What the Hosting edition does not include#

There is no AutoDJ or playlist scheduler, no billing or sign-up pages for your customers and no managed cloud service. Customers do get their own dashboard login for their station. You run the server on your own machines and connect your own billing or panel through the API or the WHMCS module.