Skip to content

Docker Deployment

Flex Video runs as Docker containers managed by Docker Compose. The recommended installation method is the offline installer, which packages all Docker images and configuration files.

Quick Start

1. Install Using Offline Installer

Download and run the offline installer, which creates the docker-compose.yml and all necessary configuration:

  1. Visit flex.blackwire-ts.com in your web browser
  2. Authenticate with your credentials (MFA required)
  3. Download the installer for your architecture (ARM64 or x86_64)
  4. Run the installer (see Offline Installation for details)

x86_64 Support (Experimental)

x86_64 installers are available for Intel/AMD systems. This platform is currently experimental. Contact support@blackwire-ts.com for access and support.

Download via Web Browser

The download portal is protected by Cloudflare Access and requires multi-factor authentication. Downloads must be performed through a web browser—command-line tools like curl or wget will not work.

2. Start Services

sudo /opt/flex/flex-video-installer-*.sh --start
# Or manually:
cd /opt/flex && docker compose up -d

3. Verify Installation

# Check containers are running
cd /opt/flex && docker compose ps

# Check API health
curl -k https://<encoder-ip>:3539/flex/health

4. Access Web Interface

Open https://<encoder-ip>:8443 in your browser.

Self-Signed Certificate

The installer generates a self-signed TLS certificate at /opt/flex/certs/. Your browser will show a certificate warning on first visit -- this is expected. Accept the warning to proceed.

Configuration

Environment Variables

Create a .env file for configuration:

# /opt/flex/.env

# Hardware decoding (set to false to enable GPU acceleration)
FLEX_FORCE_SW_DECODERS=true

# Audit logging (set to true to disable security audit logs)
# FLEX_DISABLE_AUDIT_LOG=true

The installer auto-generates additional configuration in this file. Avoid manually editing auto-generated values.

Volume Mounts

Volume Purpose Default
license_data License storage Docker volume
framegrabs Framegrab files Docker volume
fvm_data Persistent settings Docker volume
site_docs Documentation Docker volume
api_docs OpenAPI spec Docker volume

To use host directories:

volumes:
  - /path/to/license:/licensing
  - /path/to/framegrabs:/framegrabs

Video Files

To play local video files, mount a directory to /video:

volumes:
  - /path/to/videos:/video:ro

Then use file:///video/filename.ts as the source URI.

Hardware Acceleration

The installer automatically detects supported hardware and enables hardware-accelerated video decoding by setting FLEX_FORCE_SW_DECODERS=false in /opt/flex/.env.

Supported Platforms

Platform HW Decode Codecs Auto-detected Notes
Raspberry Pi 5 H.265/HEVC Yes No HW H.264 -- falls back to software
NXP i.MX8M Plus H.264, H.265, VP8, VP9 Yes Hantro G1/G2 VPU
x86_64 Intel/AMD (VAAPI) Varies by GPU Yes Experimental -- see VAAPI
NVIDIA Jetson (Orin/Xavier) Varies by model Yes V4L2 hardware codecs
NVIDIA Desktop GPU -- Future Requires nvidia-container-toolkit

To manually override, edit /opt/flex/.env:

# Set to 'false' to enable hardware decode, 'true' for software-only
FLEX_FORCE_SW_DECODERS=false

Intel VAAPI (Experimental)

Experimental x86_64 Support

x86_64 (Intel/AMD) support with VAAPI hardware acceleration is currently experimental. For assistance with x86_64 deployments, contact support@blackwire-ts.com.

On x86_64 systems with Intel 10th generation (or newer) or AMD CPUs with integrated graphics, Flex Video can use VAAPI for hardware-accelerated video decoding and encoding, significantly reducing CPU load.

The installer automatically:

  • Detects Intel integrated graphics
  • Enables /dev/dri device passthrough in docker-compose.yml
  • Sets FLEX_FORCE_SW_DECODERS=false in .env

To manually enable VAAPI, uncomment the Intel section in docker-compose.yml:

flex-av1:
  devices:
    - /dev/dri:/dev/dri

And set FLEX_FORCE_SW_DECODERS=false in .env.

Verify VAAPI

After starting services, check the container logs for VAAPI initialization messages to confirm hardware acceleration is active.

NVIDIA Jetson

Jetson video codecs (Orin, Xavier) are exposed as standard V4L2 devices. The installer automatically detects Jetson hardware and enables hardware-accelerated decoding and encoding. No nvidia-container-toolkit is required for video codec access.

The existing device passthrough (/dev:/dev) and device cgroup rules provide access to the V4L2 M2M codec devices.

Service Management

Start Services

sudo /opt/flex/flex-video-installer-*.sh --start
# Or manually:
cd /opt/flex && docker compose up -d

Stop Services

sudo /opt/flex/flex-video-installer-*.sh --stop
# Or manually:
cd /opt/flex && docker compose down

View Logs

sudo /opt/flex/flex-video-installer-*.sh --logs
# Or manually:
cd /opt/flex && docker compose logs -f

# Specific service
cd /opt/flex && docker compose logs -f flex-manager-web
cd /opt/flex && docker compose logs -f flex-api

Check Status

cd /opt/flex && docker compose ps

Restart Service

cd /opt/flex && docker compose restart flex-manager-web
cd /opt/flex && docker compose restart flex-api

Upgrading

Patch Updates (Safe)

Updates within the same major.minor version (e.g., 0.10.2 → 0.10.3) are safe to apply directly by running the new installer:

# ARM64 (Raspberry Pi, NXP i.MX8, etc.)
sudo ./flex-video-installer-0.10.3-arm64.sh

# x86_64 (Intel/AMD)
sudo ./flex-video-installer-0.10.3-amd64.sh

The installer automatically:

  • Stops running containers before upgrading
  • Loads new Docker images and cleans up old versions
  • Restarts containers if they were previously running
  • Preserves configuration and data volumes

Minor/Major Updates

For updates across minor or major versions (e.g., 0.9.x → 0.10.x), uninstall first while keeping your data:

# Uninstall but KEEP volumes when prompted
sudo /opt/flex/flex-video-installer-*.sh --uninstall
# Answer "N" to "Remove volume data?"

# Install new version
sudo ./flex-video-installer-NEW-VERSION-arm64.sh

See Offline Installation - Updating for detailed version compatibility information.

Accessing Services

Service URL Description
Web UI https://<encoder-ip>:8443 Management interface (HTTPS)
REST API https://<encoder-ip>:3539 Pipeline control for third-party integrations (HTTPS)
Documentation http://<encoder-ip>:38082 This documentation
API Docs (Swagger) http://<encoder-ip>:38081 Interactive API reference (optional)
RTSP Streams rtsp://<encoder-ip>:8554/* MediaMTX streams
RTSP Server rtsp://<encoder-ip>:8731/* GStreamer streams

Replace <encoder-ip> with your encoder's IP address.

Web UI and API

The web interface includes a built-in reverse proxy to the REST API, so browser users only need to accept one certificate (port 8443). Port 3539 is used by third-party integrations and command-line tools like curl.

Optional: Swagger UI

Swagger UI provides interactive API documentation. It is included in some installer configurations.

If installed, access at http://<encoder-ip>:38081.

Self-Signed Certificate

Before using "Try it out" in Swagger UI, you must first visit https://<encoder-ip>:3539 in your browser and accept the self-signed certificate. Otherwise, API requests from Swagger UI will silently fail with a network error.

Self-Signed Certificate

The web UI and REST API use HTTPS with a self-signed certificate. When using curl, add the -k flag to skip certificate verification. Browsers will show a certificate warning on first visit -- accept it to proceed.

Health Checks

All services include built-in health monitoring. Check their status:

# Check all container health
cd /opt/flex && docker compose ps

# Check API health
curl -k https://<encoder-ip>:3539/flex/health

Automatic Recovery

The system includes automatic health monitoring for the video processing backend. If the backend becomes unresponsive, the system will:

  1. Detect the failure within approximately 30 seconds
  2. Automatically restart the backend process
  3. Restore all running pipelines — streams resume without manual intervention

Pipeline streams will experience a brief interruption during recovery. No user action is required — the system self-heals.

Troubleshooting

Containers Won't Start

# Check logs
cd /opt/flex && docker compose logs

# Check resource limits
docker stats

# Verify ports are free
ss -tulpn | grep -E '8443|8080|3539|8554'

Permission Denied

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Camera Not Detected

# Verify device exists
ls -la /dev/video*

# Check container has access
docker exec flex-av1 ls -la /dev/video*

Out of Memory

Increase Docker memory limits or reduce container reservations in docker-compose.yml.

Web Interface Shows Blank Page or Spinner

The web interface loads but shows a blank page or infinite loading spinner. This typically occurs in Firefox when the browser blocks API requests due to the self-signed certificate.

# 1. Verify the API is reachable
curl -k https://<encoder-ip>:3539/flex/health
# Should return: OK

# 2. Open the API URL in your browser and accept the certificate
#    https://<encoder-ip>:3539
#
# 3. Return to the web interface and refresh
#    https://<encoder-ip>:8443

See Troubleshooting in Web Interface Guide for details.

Next Steps