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.

Contributions are welcome. This guide covers how to get started, submit changes, and report issues. All participants are expected to follow the Code of Conduct.

​
Getting started

1

Fork and clone

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/<your-username>/audiostreaming-stack.git
cd audiostreaming-stack
2

Configure

cp .env.example .env
Fill in your values. See configuration for details.
3

Add emergency audio

Place at least one fallback audio file (MP3, FLAC, or WAV) in emergency-audio/.
4

Install dependencies and build

Use the interactive installer with the --dev flag to set up a full development environment:
./install.sh --dev
Or build containers and install dependencies manually:
docker compose build
docker compose up -d
./install-dev-deps.sh

​
Development workflow

ServiceHow to iterate
dashboardcd apps/dashboard && npm install && npm run dev
status-apiEdit apps/status-api/server.py, then docker compose restart status-api
analyticsEdit services/analytics/tracker.py, then docker compose restart analytics
liquidsoapEdit services/streaming/liquidsoap/radio.liq, then docker compose restart liquidsoap
nginxEdit infrastructure/nginx/nginx.conf, then docker compose restart nginx

​
Code style

  • Python — ruff check services/analytics/ apps/status-api/ (config in pyproject.toml)
  • TypeScript — npm run lint inside apps/dashboard/
  • Shell — set -e, 4-space indent, double-quoted variables
  • Dockerfiles — must pass hadolint

​
Commit messages

Use Conventional Commits. Valid types: feat, fix, chore, docs, refactor, test, ci, style, perf. Examples: 
feat(dashboard): add stream health indicator
fix(liquidsoap): handle empty fallback playlist
docs: update environment variable table

​
Submitting a pull request

  1. Create a branch from main (git checkout -b feat/my-feature)
  2. Keep each PR focused on a single feature or fix
  3. Run linters locally before pushing
  4. Fill in the pull request template completely
  5. Reference any related issue with Closes #123
  6. Expect a maintainer review within a few business days; address feedback with additional commits (do not force-push after review starts)

​
Adding environment variables

If your change introduces new environment variables:
  • Add them to .env.example with a sensible default or blank value
  • Document them in the configuration table in README.md

​
Reporting bugs

Use the Bug report issue template on GitHub. Include your OS, Docker version, and relevant logs: 
docker compose logs --tail=50 <service>
Do not open public issues for security vulnerabilities. See security instead.

​
Communication

  • GitHub Issues — bug reports and feature requests
  • GitHub Discussions — questions and design conversations
  • Slack — join the Sonicverse OSS Slack for real-time discussion