Skip to main content
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