Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sonicverse.eu/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites:
  • A Linux server (Ubuntu/Debian recommended)
  • Docker and Docker Compose installed
  • A domain name pointed at your server
  • Ports 80, 443, 8010, and 8011 open
For a reliable, high-performance hosting option, consider Hetzner Cloud — competitive prices and ideal for audio streaming infrastructure. Sign up using the link below to receive a €20 promo code valid for all Cloud products. It also helps support Sonicverse internal services and sandboxes.
hetzner-cloud

Get started on Hetzner Cloud

Sign up and receive €20 in free cloud credits.

​
Option A: One-liner installation

The fastest way to get started. This command clones the repository and runs the interactive installer: 
bash <(curl -fsSL https://sonicverse.short.gy/install-audiostack)
This is equivalent to the “minimal deployment” below and works from any directory.

​
Option B: Interactive installer

Choose an installation mode based on your needs.
Uses pre-built images from Docker Hub. No local build tools required — the fastest option for production.
git clone https://github.com/sonicverse-eu/audiostreaming-stack.git
cd audiostreaming-stack
./install.sh
This installs only what you need to run the stack: Docker, a .env configuration file, and pre-built container images from Docker Hub.

​
Container registries

Pre-built images are published to both Docker Hub (primary) and GitHub Container Registry (mirror). The default configuration pulls from Docker Hub.
RegistryImage prefixRole
Docker Hubdocker.io/sonicverse/audiostreaming-stack-*Primary (default)
GHCRghcr.io/sonicverse-eu/audiostreaming-stack/*Mirror
If you previously pinned images to GHCR, they continue to work. No changes are required for existing deployments.

​
Option C: Manual setup

1

Clone and configure

git clone https://github.com/sonicverse-eu/audiostreaming-stack.git
cd audiostreaming-stack
cp .env.example .env
Edit .env with your values. See configuration for all available variables.
2

Add emergency audio

Place a fallback audio file that plays when both studio streams are offline:
cp /path/to/your/fallback.mp3 emergency-audio/fallback.mp3
3

Obtain SSL certificate

./init-letsencrypt.sh
Set LETSENCRYPT_STAGING=1 in your .env to test with staging certificates first.
4

Start the stack

docker compose up -d
If you enabled the optional status panel (ENABLE_STATUS_PANEL=1 in .env), include the profile flag:
docker compose --profile status-panel up -d
The interactive installer handles this automatically.
5

Connect your studio encoder

Configure BUTT or any Icecast-compatible encoder:Primary stream:
  • Host: your server IP
  • Port: 8010
  • Mount: /primary
  • Password: your HARBOR_PASSWORD from .env
  • Format: MP3 CBR 320 kbps
Fallback stream:
  • Host: your server IP
  • Port: 8011
  • Mount: /secondary
  • Password: your HARBOR_PASSWORD from .env
  • Format: MP3 CBR 192 kbps
Command-line encoder profiles (LAME):
# Primary (320 kbps)
lame -r -s 44.1 -b 320 -x - -

# Fallback (192 kbps)
lame -r -s 44.1 -b 192 -x - -
6

Verify

Check that everything is running:
  • Icecast admin: https://<host>/icecast-admin/
  • Test stream: open https://<host>/listen/stream-mp3-128 in VLC
  • HLS: open https://<host>/hls/live.m3u8 in Safari or VLC

​
Install development dependencies separately

If you already ran ./install.sh without --dev and now want to add development dependencies: 
./install-dev-deps.sh
This installs Node.js dependencies for the dashboard and Python dependencies for analytics and the status API. Available flags:
FlagDescription
--ciDeterministic installs using lockfiles
--python-userInstall Python packages with --user
--skip-nodeSkip dashboard (JavaScript) dependencies
--skip-pythonSkip analytics and status API (Python) dependencies

​
Install Docker

If you don’t have Docker installed yet: 
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Log out and back in for group changes to take effect.

​
Updating the stack

When you run the installer on a server that already has the stack running, it detects the existing deployment and prompts you to Update, Reinstall, or Cancel. 
./install.sh
Choosing Update runs the following steps automatically:
  1. Backup — Tags the Docker image for every running service so it can be restored if the update fails.
  2. Pull — Fetches the latest code from the repository and pulls new container images from Docker Hub.
  3. Rebuild — Rebuilds any locally built images to pick up configuration changes.
  4. Apply — Starts the updated containers with zero downtime using docker compose up -d --remove-orphans.
  5. Rollback — If step 4 fails, the installer restores the backed-up images and restarts the previous version automatically.
The update process keeps your .env file and data volumes intact. Only container images are changed.

​
Manual update

If you prefer to update manually without the installer: 
git pull origin main
docker compose pull
docker compose build
docker compose up -d --remove-orphans
If you use the status panel, add --profile status-panel to each docker compose command: 
docker compose --profile status-panel pull
docker compose --profile status-panel build
docker compose --profile status-panel up -d --remove-orphans
Manual updates do not include automatic rollback. If something goes wrong, you will need to restore images or redeploy manually.

​
Next steps

Configuration

Customize all environment variables for your station.

Stream endpoints

See all available listener endpoints and formats.