Skip to content

20. Adding New Streaming Services

This guide explains how to add support for new streaming services to docker-rtmp-multistream.

20.1 Overview

Adding a new streaming service involves two main steps:

  1. Service Configuration - Create nginx configs, environment variables, and pre-init scripts
  2. Service Testing - Add comprehensive automated tests

Both steps are required for a complete service implementation.

20.2 Service Patterns

Before implementing a new service, choose the appropriate pattern. See Service Patterns Reference for a detailed comparison of Simple Relay and Transformer patterns, including use cases, pros/cons, and examples.

20.3 Quick Start

20.3.1 1. Configuration

Follow the Service Configuration guide to:

  • Create nginx RTMP configuration files (apps/ and optionally transformers/)
  • Define environment variables in Dockerfile and env/relay.env
  • Add commented includes to app.conf
  • Create pre-init script (90_configure_{service}.sh)
  • Make script executable

20.3.2 2. Testing

Follow the Service Testing guide to:

  • Add unit tests to tests/02_unit_tests.sh (service enablement, variable replacement, security)
  • Add integration test to tests/03_integration_tests.sh (container startup)
  • Add validation tests to tests/00_validation_tests.sh (if new validation functions added)
  • Run all tests: ./tests/test.sh
  • Perform manual end-to-end testing

20.3.3 3. Documentation

Add service-specific documentation:

  • Create docs/services/{service}.md with:
  • Overview and configuration variables
  • Quality settings and recommendations
  • Troubleshooting tips
  • Update mkdocs.yml navigation to include your service

20.4 Implementation Checklist

Use this checklist to track your progress:

20.4.1 Configuration

  • Created nginx config files (apps/ and/or transformers/)
  • Added environment variables to Dockerfile
  • Added environment variables to env/relay.env
  • Added commented includes to app.conf
  • Created pre-init script with validation
  • Made script executable (chmod +x)

20.4.2 Testing

  • Added 4-5 unit tests (enable, skip, variables, security, transformer if applicable)
  • Added integration test (container startup)
  • Added validation tests (if new functions added)
  • All tests pass: ./tests/test.sh exits with code 0
  • Manual end-to-end testing completed

20.4.3 Documentation

  • Created service documentation page
  • Updated navigation in mkdocs.yml
  • Added to main README (if appropriate)

20.5 Best Practices

  1. Validate early: Check for required environment variables at the start of pre-init scripts
  2. Use validation functions: Always validate inputs using validate_input.sh to prevent injection attacks
  3. Fail gracefully: Exit with code 0 if service shouldn't be enabled, exit with code 1 for validation errors
  4. Escape properly: Use escape_for_sed() when substituting values to handle special characters safely
  5. Log clearly: Echo meaningful messages (e.g., "SERVICE configured and enabled")
  6. Test thoroughly: Add tests to all relevant test suites
  7. Security first: Always test that malicious inputs are rejected
  8. Document comprehensively: Help users configure and troubleshoot your service

20.6 Examples

Study existing service implementations:

20.6.1 Simple Relay (YouTube)

20.6.2 Transformer (Twitch)

20.7 Detailed Guides

20.8 See Also