rubenc2/rist_platform repository overview

⁠RIST Connection Manager

Containerized RIST stream/tunnel/mux manager with a web UI, built on top of librist.

⁠Quick Reference

• Image: rubenc2/rist_platform
• Stable tag: 1.0.4
• Latest tag: latest -> 1.0.4
• Active pre-release test tag: none (1.0.4.rc9 was promoted)
• Pre-release track: 1.0.4.rc* (current), 1.0.4.b* (historical), historical 1.0.3.b* / 1.0.3.rc* (promoted to stable)
• librist version:
  • stable (1.0.4): 0.2.12
  • previous stable (1.0.3): 0.2.11
• Architectures: linux/amd64, linux/arm64
• Multi-arch digest (1.0.4/latest): sha256:3c654d1cd3dc6d0d814cec6c118d4e7e05cc1559d26099804e830d8ded933509
• Multi-arch digest (1.0.4.rc9): sha256:d022d947cbed8778572f734dcbe0362b450ea433cdb4bcd6d008520242dc185e
• Runtime mode: Linux network_mode: host (recommended; required for TUN/TAP flows)

⁠1.0.4 Release Status

Current release: 1.0.4 Status: promoted to stable and latest.

Validation checklist (current state):

• Multi-host deploy checks passed (AWS + local hosts).
• API reachability and stats window responses verified.
• Receiver watch reopen regression checks passed.
• Active stream/tunnel delete guard behavior validated.
• Generated source tee muxrate fix validated with analyzer and field behavior.
• Documentation synchronized for 1.0.4.

⁠What Is Included In 1.0.4

• Runtime baseline upgrade to librist 0.2.12 with compatibility path for 0.2.11.
• Receiver stale-metrics/dead-flow guard to prevent misleading non-zero telemetry during no-payload outages.
• Self-contained/offline UI-doc assets (local Video.js + local Swagger UI assets; no CDN dependency at runtime).
• Stream card mode badges (Tx/Rx) moved into the metadata line for better badge/status readability on crowded cards.
• Stream card mux/tunnel association moved into its own full-width row to prevent overlap on mux-managed and tunnel-managed cards.
• Dashboard line-gap rendering fix for large time gaps (no misleading diagonal bridge).
• Active stream/tunnel/mux delete protection (UI + API disconnect-first enforcement).
• Receiver watch reopen hardening and inactive-watch API guard.
• Receiver watch first-open prewarm/readiness hardening (live FFmpeg process + fresh playable HLS segments required).
• Generated shared-source multicast containment hardening (loopback-bound emit/join controls).
• Generated test-stream tee muxrate fix (restored null-packet behavior and measurable NPD impact).
• Top-bar host CPU indicator (green/orange/red) with /api/system/cpu backend endpoint.
• Same-card toggle close UX for stream/tunnel/mux cards already open in the details pane.

⁠Incremental Release Notes

⁠1.0.4 (Stable)

1.0.4 (sha256:3c654d1cd3dc6d0d814cec6c118d4e7e05cc1559d26099804e830d8ded933509)

• Promoted the 1.0.4 release-candidate track to stable.
• latest now points to 1.0.4.
• Stable image is built with UI/API version metadata set to 1.0.4.
• Includes the rc9 UX polish that lets operators close an already-open details pane by clicking the same stream/tunnel/mux card again.

⁠1.0.3 (Stable)

1.0.3 (sha256:14577e3424c5319faf1ede9e8d29827820b6ca28a9b943322e34b0e835f763b4)

• Promotion of the 1.0.3 pre-release track to stable (b1..b10, rc1..rc3).
• Release focus: intuitive UI/UX, in-app operator guidance, and safer day-2 workflows.
• Includes rc3 UX polish:
  • Settings > Test Stream save shows immediate Saving... feedback and click-guard behavior.
  • Settings > Tools interface selector hides Docker/virtual interfaces for cleaner choices.

⁠1.0.2 (Stable)

1.0.2 (sha256:38d22a530f2b14adf6f609f412736622a14b1adfaf4e694e9b614b29e0a05c78)

• Includes all 1.0.2.b1 through 1.0.2.rc3 changes.
• Main/Advanced single-stream: Stream ID optional in direct mode.
• Main/Advanced mux-group: Stream ID required and even.
• Dashboard includes retransmit bitrate graph with adaptive units.
• Branding settings use Height + Y Offset with dark preview for white logos.
• Main/Advanced direct save flow no longer auto-fills Stream ID with 0 in optional mode.

⁠1.0.1

Bug fixes:

• Fixed false stream error latch caused by transient librist timeout warning lines (for example: Listening peer 1 timed out after ... ms) during startup/reconnect windows.
• Previous behavior: UI/API could stay in error even while bitrate/RTT/log stats continued to update normally.
• 1.0.1 behavior: runtime auto-recovers error -> connected when fresh metrics/log evidence confirms the peer session is established.
• Dashboard graph interaction improved for operators:
  • hover now shows exact timestamp/value on spikes,
  • live window baseline is now ~5m,
  • Reset Graph From Now flushes persisted historical graph data for the selected item.

Operational:

• No API contract changes in this patch release.

⁠1.0.0

Bug fixes:

• Stream/tunnel connected-state semantics tightened: sender no longer shows misleading connected/up state before peer-side handshake evidence.
• Dashboard x-axis behavior fixed for historical windows (1h, 12h, 24h, 48h): axis now stays anchored to the selected full time window (ending at now), instead of collapsing to recent sample span.
• Mux stream membership add/remove flow corrected and decoupled from tunnel-only validation errors.
• Stats API contract finalized for 1.0.0: payload uses items as the only series field.

Enhancements:

• Persisted SQLite time-series stats for stream/tunnel telemetry.
• Stats API windowing + downsample controls (window, step).
• Dashboard window selector (Live, 1h, 12h, 24h, 48h) with live-forward behavior at window-dependent granularity.
• Configurable retention cleanup (STATS_RETENTION_DAYS, STATS_RETENTION_CLEANUP_INTERVAL_SECONDS).

Operational:

• Recommended deployment remains Linux network_mode: host.
• latest is intended to track the current stable release tag.

Known issue reference (RTT):

• Upstream librist telemetry can intermittently emit corrupted RTT/AVG RTT samples on some paths (for example very large invalid values), which can create unrealistic dashboard spikes.
• Current workaround in 1.0.3: prefer raw rtt when present, reject invalid/out-of-range RTT samples, and keep the last-known-good RTT in the UI path.
• Runtime threshold is configurable with MAX_VALID_RTT_MS (default 100000).
• Normalization plan: once the upstream RTT fix is available and validated, this defensive workaround will be reduced/removed accordingly.

⁠How The System Works

• The container runs a FastAPI backend + static frontend UI.
• The backend manages multiple ristsender / ristreceiver processes.
• Configuration/state is persisted in /data/rist_manager.db.
• TLS is enabled by default; if cert/key do not exist, a self-signed cert is generated automatically.
• Three operational layers are exposed in the UI/API:
  • Streams: single sender/receiver flows (Simple/Main/Advanced profiles).
  • Tunnels: client/server templates for main/advanced transport and optional TUN/TAP parameters.
  • Mux Groups: multi-stream grouped operation with shared RIST construction logic and aggregated telemetry.

⁠Acknowledgement

This project is built on top of librist.

librist is maintained by Sergio Ammirata (SipRadius) and contributors in the VideoLAN project:

• https://code.videolan.org/rist/librist⁠

⁠License

• Project source code is licensed under GPL-3.0-or-later.
• Copyright: (c) 2026 RIST Connection Manager contributors.
• Runtime dependencies are under their own licenses:
  • librist: BSD-2-Clause
  • FFmpeg: LGPL/GPL components (this image uses GPL-enabled FFmpeg build)
  • x264: GPL-2.0-or-later
• See THIRD_PARTY_LICENSES.md in the repository for more detail.

⁠docker-compose.yml (copy/paste, host networking recommended)

This is the current compose format used by the project for Linux deployments.

services:
  rist-manager:
    image: rubenc2/rist_platform:1.0.4
    container_name: rist_platform
    network_mode: host
    build:
      context: .
      dockerfile: Dockerfile
      args:
        LIBRIST_VERSION: ${LIBRIST_VERSION:-v0.2.12}
    environment:
      LIBRIST_VERSION: ${LIBRIST_VERSION:-0.2.12}
      LIBRIST_AVAILABLE_VERSIONS: ${LIBRIST_AVAILABLE_VERSIONS:-0.2.11,0.2.12}
      DATA_DIR: /data
      FRONTEND_DIR: /app/frontend
      ACCESS_SESSION_TTL_SECONDS: ${ACCESS_SESSION_TTL_SECONDS:-43200}
      HTTP_PORT: ${HTTP_PORT:-8080}
      TLS_ENABLED: ${TLS_ENABLED:-1}
      TLS_PORT: ${TLS_PORT:-8443}
      TLS_CERT_FILE: ${TLS_CERT_FILE:-/data/tls/tls.crt}
      TLS_KEY_FILE: ${TLS_KEY_FILE:-/data/tls/tls.key}
      TLS_HOSTNAMES: ${TLS_HOSTNAMES:-localhost,127.0.0.1}
      WATCH_COPY_START_TIMEOUT_S: ${WATCH_COPY_START_TIMEOUT_S:-10}
      WATCH_PLAYABLE_MIN_SEGMENTS: ${WATCH_PLAYABLE_MIN_SEGMENTS:-2}
      WATCH_SEGMENT_STALE_AFTER_S: ${WATCH_SEGMENT_STALE_AFTER_S:-15}
      RECEIVER_WATCH_TAP_BASE_PORT: ${RECEIVER_WATCH_TAP_BASE_PORT:-17000}
      RECEIVER_WATCH_TAP_PORT_SPAN: ${RECEIVER_WATCH_TAP_PORT_SPAN:-20000}
      TEST_STREAM_PRIMARY_PORT: ${TEST_STREAM_PRIMARY_PORT:-15000}
      TEST_STREAM_WATCH_PORT: ${TEST_STREAM_WATCH_PORT:-15001}
      TEST_STREAM_DISTRIBUTION_MODE: ${TEST_STREAM_DISTRIBUTION_MODE:-multicast}
      TEST_STREAM_MULTICAST_GROUP: ${TEST_STREAM_MULTICAST_GROUP:-239.255.42.99}
      TEST_STREAM_MULTICAST_HOST_LOCAL_ONLY: ${TEST_STREAM_MULTICAST_HOST_LOCAL_ONLY:-1}
      TEST_STREAM_MULTICAST_MIFACE: ${TEST_STREAM_MULTICAST_MIFACE:-lo}
      TEST_STREAM_MULTICAST_LOCALADDR: ${TEST_STREAM_MULTICAST_LOCALADDR:-127.0.0.1}
      TEST_STREAM_MULTICAST_TTL: ${TEST_STREAM_MULTICAST_TTL:-1}
      MAX_VALID_RTT_MS: ${MAX_VALID_RTT_MS:-100000}
      STATS_RETENTION_DAYS: ${STATS_RETENTION_DAYS:-14}
      STATS_RETENTION_CLEANUP_INTERVAL_SECONDS: ${STATS_RETENTION_CLEANUP_INTERVAL_SECONDS:-3600}
      LIVE_STATS_BUFFER_LIMIT: ${LIVE_STATS_BUFFER_LIMIT:-12000}
      RECONNECT_INCIDENT_WINDOW_SECONDS: ${RECONNECT_INCIDENT_WINDOW_SECONDS:-30}
      AUDIT_LOG_ENABLED: ${AUDIT_LOG_ENABLED:-1}
      AUDIT_LOG_RETENTION_DAYS: ${AUDIT_LOG_RETENTION_DAYS:-30}
      AUDIT_LOG_CLEANUP_INTERVAL_SECONDS: ${AUDIT_LOG_CLEANUP_INTERVAL_SECONDS:-3600}
      AUDIT_LOG_MAX_ROWS: ${AUDIT_LOG_MAX_ROWS:-500000}
      AUDIT_LOG_DOWNLOAD_MAX_ROWS: ${AUDIT_LOG_DOWNLOAD_MAX_ROWS:-50000}
      STREAM_LOG_MAX_MB: ${STREAM_LOG_MAX_MB:-100}
    volumes:
      - rist_manager_data:/data
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
      - ${GPU_DRIVER_DEVICE:-/dev/dri:/dev/dri}
    restart: unless-stopped

volumes:
  rist_manager_data:

GPU_DRIVER_DEVICE defaults to /dev/dri:/dev/dri. Override it for hosts that expose a specific render node path.

⁠Generated Test Stream And Watch Behavior

• Default generated-source mode is shared local multicast (TEST_STREAM_DISTRIBUTION_MODE=multicast), so one generated test feed can be attached to one or many sender streams.
• Host containment defaults:
  • TEST_STREAM_MULTICAST_HOST_LOCAL_ONLY=1
  • TEST_STREAM_MULTICAST_MIFACE=lo
  • TEST_STREAM_MULTICAST_LOCALADDR=127.0.0.1
  • This keeps generated multicast host-contained (loopback only), avoiding multicast leakage to external NICs.
• Quick rollback to prior behavior: set TEST_STREAM_DISTRIBUTION_MODE=legacy and recreate the container (restores single-sender unicast assignment behavior).
• The test generator produces a primary UDP source and a watch UDP source.
• When test-stream generation is enabled, generated-source watch HLS is prewarmed in the background.
• Opening Watch Generated Feed reuses that running watch session instead of spawning duplicate sessions.
• Receiver stream watches follow the same model: watch sessions are prewarmed on receiver connect and reused on Watch click.
• Closing the watch dialog closes the player only; HLS generation remains active while generator is enabled.
• Disabling the test stream stops the generator and cleans generated watch/HLS artifacts.
• A short black frame at watch open is expected while initial HLS segments are detected by the player.
• Current watch HLS packaging defaults:
  • -c:v copy -c:a copy
  • -hls_time 4
  • -hls_list_size 3
  • -hls_flags delete_segments+append_list
• Current generator overlay/audio defaults:
  • scrolling label at centered-x and about 40px above vertical center,
  • dual beep audio inputs (sine=frequency=440:beep_factor=4),
  • metadata includes service_provider=RIST, service_name=RIST_Test.

⁠Start

docker compose pull
docker compose up -d

UI/API endpoints:

• http://<host>:8080
• https://<host>:8443 (self-signed by default)

Optional bridge-mode startup (secondary / non-TUN testing):

docker compose -f docker-compose.yml -f docker-compose.bridge.yml up -d

⁠Bridge Mode Usage (Optional)

Bridge mode is intended for non-TUN testing workflows only.

• Compose override: docker-compose.bridge.yml
• Default published ports:
  • 8080/tcp, 8443/tcp
  • 12000-12003/udp
• TUN/TAP workflows are not supported in bridge mode.

Recommended bridge-mode lifecycle:

docker compose -f docker-compose.yml -f docker-compose.bridge.yml down
docker compose -f docker-compose.yml -f docker-compose.bridge.yml pull
docker compose -f docker-compose.yml -f docker-compose.bridge.yml up -d
docker compose -f docker-compose.yml -f docker-compose.bridge.yml ps

Operational guidance:

• Point peer systems to the host IP address, not container loopback.
• For sender UDP input listeners, use one of the published UDP ports (for example udp://@:12000).
• If your lab needs a different UDP range, create a local override with custom ports: mappings.

⁠Why Host Networking

Run the container with network_mode: host because RIST transport depends on direct UDP behavior and predictable endpoint binding:

• Avoids Docker NAT side effects on RIST data/control paths (port and port+1).
• Allows reliable listen/caller behavior for stream, tunnel, and mux workflows.
• Required when using TUN/TAP (/dev/net/tun) so interface lifecycle and traffic are handled at host network scope.
• Recommended for hardware test-stream encode: map GPU driver device (default GPU_DRIVER_DEVICE=/dev/dri:/dev/dri) for VAAPI.

Bridge mode may work for limited non-TUN tests, but host networking is the intended deployment model.

⁠UI Settings Customization

From Settings in the web UI you can customize:

• Branding logo upload/display (png, jpg, webp, gif, svg).
• Access-Control enable/disable.
• Username/password login.
• MFA with TOTP using authenticator apps (QR setup/rotation).

⁠Environment Variables

• HTTP_PORT (default 8080)
• TLS_ENABLED (default 1)
• TLS_PORT (default 8443)
• TLS_CERT_FILE (default /data/tls/tls.crt)
• TLS_KEY_FILE (default /data/tls/tls.key)
• TLS_HOSTNAMES (default localhost,127.0.0.1)
• LIBRIST_VERSION (default 0.2.12)
• LIBRIST_AVAILABLE_VERSIONS (default 0.2.11,0.2.12)
• DATA_DIR (default /data)
• FRONTEND_DIR (default /app/frontend)
• ACCESS_SESSION_TTL_SECONDS (default 43200)
• WATCH_COPY_START_TIMEOUT_S (default 10)
• WATCH_PLAYABLE_MIN_SEGMENTS (default 2)
• WATCH_SEGMENT_STALE_AFTER_S (default 15)
• RECEIVER_WATCH_TAP_BASE_PORT (default 17000)
• RECEIVER_WATCH_TAP_PORT_SPAN (default 20000)
• TEST_STREAM_PRIMARY_PORT (default 15000)
• TEST_STREAM_WATCH_PORT (default 15001)
• TEST_STREAM_DISTRIBUTION_MODE (default multicast, options: multicast, legacy)
• TEST_STREAM_MULTICAST_GROUP (default 239.255.42.99)
• TEST_STREAM_MULTICAST_HOST_LOCAL_ONLY (default 1)
• TEST_STREAM_MULTICAST_MIFACE (default lo)
• TEST_STREAM_MULTICAST_LOCALADDR (default 127.0.0.1)
• TEST_STREAM_MULTICAST_TTL (default 1)
• MAX_VALID_RTT_MS (default 100000)
• GPU_DRIVER_DEVICE (default /dev/dri:/dev/dri)
• STATS_RETENTION_DAYS (default 14)
• STATS_RETENTION_CLEANUP_INTERVAL_SECONDS (default 3600)
• LIVE_STATS_BUFFER_LIMIT (default 12000)
• AUDIT_LOG_ENABLED (default 1)
• AUDIT_LOG_RETENTION_DAYS (default 30)
• AUDIT_LOG_CLEANUP_INTERVAL_SECONDS (default 3600)
• AUDIT_LOG_MAX_ROWS (default 500000)
• AUDIT_LOG_DOWNLOAD_MAX_ROWS (default 50000)
• RECONNECT_INCIDENT_WINDOW_SECONDS (default 30)
• STREAM_LOG_MAX_MB (default 100)

⁠Environment Variable Tips (librist Upgrades)

Important behavior:

• LIBRIST_VERSION in compose build.args determines the librist source tag compiled into the image.
• Runtime LIBRIST_VERSION should match the compiled version so UI/API version reporting is accurate.
• LIBRIST_AVAILABLE_VERSIONS controls the Library selector list.
• Selecting a different target_version in UI does not switch binaries until the image is rebuilt.

How to adopt a new librist release (example 0.2.12):

1. Set env values (for example in .env):

LIBRIST_VERSION=v0.2.12
LIBRIST_AVAILABLE_VERSIONS=0.2.11,0.2.12

1. Rebuild and restart:

docker compose down
docker compose build --no-cache rist-manager
docker compose up -d

1. Verify:

curl -s http://<host>:8080/api/system/librist

If you use prebuilt Docker Hub images, env vars alone cannot replace the bundled librist binary. Use an image tag that already includes the new librist release, or rebuild locally with updated LIBRIST_VERSION.

⁠Persistent Data

Stored in volume rist_manager_data mounted at /data:

• rist_manager.db (config + runtime metadata)
• tls/ (certificate/key when auto-generated)
• branding assets (if uploaded from UI)
• logs/streams/stream_<id>.log (full per-session stream logs)

⁠Networking And Tunnel Requirements

• Recommended deployment is Linux host networking (network_mode: host).
• For TUN/TAP workflows provide CAP_NET_ADMIN.
• For TUN/TAP workflows map /dev/net/tun.
• For VAAPI test-stream encoding map a GPU driver device; default is /dev/dri:/dev/dri.
• Override the default mapping with GPU_DRIVER_DEVICE (example: /dev/dri/renderD128:/dev/dri/renderD128).
• Ensure RIST UDP control/data paths are open end-to-end (port and port+1).

⁠Health/API

• Health: GET /api/health
• OpenAPI: GET /openapi.json
• Interactive docs: GET /docs
• API docs/watch frontend dependencies are bundled locally for private/offline networks (no runtime CDN dependency).
• Stats endpoints (/api/connections/{id}/stats, /api/tunnels/{id}/stats):
  • Series field: items