Docker Setup - theweebcoders/CommercialBreaker GitHub Wiki

Docker Setup Guide

Complete guide for running CommercialBreaker & Toonami Tools in Docker containers.

Quick Start

Option 1: Pre-built Image (Recommended)

docker run -p 8081:8081 -p 8083:8083 \
  -v "/path/to/your/Anime:/app/anime" \
  -v "/path/to/your/Bumps:/app/bump" \
  -v "/path/to/your/SpecialBumps:/app/special_bump" \
  -v "/path/to/your/Working:/app/working" \
  -v "/path/to/your/Commercials:/app/commercials" \
  --name commercialbreaker \
  tim000x3/commercial-breaker:latest

Option 2: Local Build

git clone https://github.com/theweebcoders/CommercialBreaker.git
cd CommercialBreaker
cp example.env .env
# Edit .env with your paths
docker compose up -d

Environment Configuration

Required .env File

Create .env in the project root:

# Required folder paths (absolute paths recommended)
ANIME_FOLDER=/path/to/your/anime
BUMPS_FOLDER=/path/to/your/bumps
SPECIAL_BUMPS_FOLDER=/path/to/your/special_bumps
WORKING_FOLDER=/path/to/your/working
COMMERCIAL_FOLDER=/path/to/your/commercials  # For ComBreakDirect pre-rendered breaks

# Optional database configuration
DB_FOLDER_PATH=/path/to/your/database        # For database persistence across container restarts
DB_DIR=/data                                 # Internal database directory
DB_PATH=/data/Toonami.db                      # Internal database path (usually don't need to change)

Database Configuration:

  • DB_FOLDER_PATH: Recommended for database persistence across container restarts
  • DB_DIR: Internal database directory (defaults to /data)
  • DB_PATH: Internal database path (defaults to /data/Toonami.db)
  • _pre_rendered_breaks folder: Auto-created for ComBreakDirect, prevents startup race conditions

Path Requirements

Folder paths must:

  • Use absolute paths from host system
  • Point to existing directories
  • Be accessible by Docker daemon
  • Have appropriate read/write permissions

Example structure:

/media/anime/
├── Shows/              # → ANIME_FOLDER
├── Bumps/              # → BUMPS_FOLDER
├── SpecialBumps/       # → SPECIAL_BUMPS_FOLDER
└── Working/            # → WORKING_FOLDER

Docker Compose Setup

Full docker-compose.yml

version: '3.8'

services:
  commercialbreaker:
    build: .
    # Or use pre-built image:
    # image: tim000x3/commercial-breaker:latest
    container_name: commercialbreaker
    ports:
      - "8081:8081"                 # WebUI (Absolution)
      - "8083:8083"                 # ComBreakDirect streaming server
    volumes:
      - "${ANIME_FOLDER}:/app/anime"
      - "${BUMPS_FOLDER}:/app/bump"
      - "${SPECIAL_BUMPS_FOLDER}:/app/special_bump"
      - "${WORKING_FOLDER}:/app/working"
      - "${COMMERCIAL_FOLDER}:/app/commercials"  # Pre-rendered commercial breaks
      - "./data:/data"               # Database persistence
      - "./logs:/app/logs"           # Log persistence
    environment:
      - ANIME_FOLDER=/app/anime
      - BUMPS_FOLDER=/app/bump
      - SPECIAL_BUMPS_FOLDER=/app/special_bump
      - WORKING_FOLDER=/app/working
      - COMMERCIAL_FOLDER=/app/commercials
      - DB_DIR=/data
      - DB_PATH=/data/Toonami.db
      - LOG_LEVEL=INFO
      - CBDIRECT_HOST=0.0.0.0       # ComBreakDirect bind address
      - CBDIRECT_PORT=8083          # ComBreakDirect port
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Optional: Include DizqueTV
  dizquetv:
    image: vexorian/dizquetv:latest  # Use DizqueTV 1.7+
    container_name: dizquetv
    ports:
      - "8000:8000"
    volumes:
      - "./dizquetv-config:/home/node/app/.dizquetv"
      - "${ANIME_FOLDER}:/media/anime:ro"
      - "${BUMPS_FOLDER}:/media/bumps:ro"
    restart: unless-stopped

  # Optional: Include Plex
  plex:
    image: plexinc/pms-docker:latest
    container_name: plex
    ports:
      - "32400:32400"
    volumes:
      - "./plex-config:/config"
      - "${ANIME_FOLDER}:/media/anime:ro"
    environment:
      - PLEX_CLAIM=your-claim-token
    restart: unless-stopped

Minimal Setup

For just CommercialBreaker:

version: '3.8'

services:
  commercialbreaker:
    image: tim000x3/commercial-breaker:latest
    container_name: commercialbreaker
    ports:
      - "8081:8081"
    environment:
      - ANIME_FOLDER=/app/anime
      - BUMPS_FOLDER=/app/bump
      - SPECIAL_BUMPS_FOLDER=/app/special_bump
      - WORKING_FOLDER=/app/working
    restart: unless-stopped

Container Management

Starting Services

# Start all services
docker compose up -d

# Start specific service
docker compose up -d commercialbreaker

# View logs
docker compose logs -f commercialbreaker

# Check status
docker compose ps

Updating

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d --force-recreate

# Clean up old images
docker image prune

Stopping Services

# Stop all services
docker compose down

# Stop and remove volumes (careful!)
docker compose down -v

# Force stop
docker compose kill

Volume Mounts Explained

Content Volumes

volumes:
  - "${ANIME_FOLDER}:/app/anime"        # Anime collection
  - "${BUMPS_FOLDER}:/app/bump"         # Toonami bumps and transitions
  - "${SPECIAL_BUMPS_FOLDER}:/app/special_bump"  # Music videos, extras
  - "${WORKING_FOLDER}:/app/working"    # Processing workspace (read/write)
  - "${COMMERCIAL_FOLDER}:/app/commercials"  # Pre-rendered commercial breaks (ComBreakDirect)

Data Persistence

volumes:
  - "./data:/app/data"                  # Database and configuration
  - "./logs:/app/logs"                  # Application logs
  - "./cache:/app/cache"                # API response cache

ComBreakDirect Channel Persistence

ComBreakDirect's channel state lives in channels.json. The path depends on which process is hosting CBD in your container:

  • run_server.py subprocess (launched by start.sh — the canonical Docker CBD instance): writes to /app/combreak_direct_data/channels.json because it doesn't pass --docker in sys.argv. This path is in the container's writable layer, NOT a bind-mounted volume, so a docker compose down + up cycle wipes it.
  • Absolution thread fallback (_ensure_combreakdirect_server inside main.py --webui --docker): writes to /app/working/combreak_direct/channels.json, which IS bind-mounted via ${WORKING_FOLDER}:/app/working and survives container recreate.

Because ComBreakDirect channels are infinite by default — the LineupExtender watchdog keeps them growing forever — losing channels.json means losing the entire built-up infinite lineup (potentially weeks or months of accumulated extension history). If you plan to do docker compose down for any reason, back up channels.json first:

docker exec commercialbreaker cp /app/combreak_direct_data/channels.json /app/working/channels-backup.json
# Or via the bind-mounted working folder:
cp "${WORKING_FOLDER}/channels-backup.json" /some/safe/place/

The cleaner long-term fix is to add an explicit bind mount for /app/combreak_direct_data in your compose so the subprocess's storage is also persisted:

volumes:
  - "./cbdirect_state:/app/combreak_direct_data"  # Persist subprocess channels.json

Infinite Channel Background Activity

Each ComBreakDirect channel spawns a LineupExtender watchdog that arms a threading.Timer to fire INFINITE_EXTEND_LEAD_MS (default 3 hours) before the channel's last program ends. The timer runs inside the same CBD process — no extra containers, no extra ports, no extra mounts required. When it fires it runs ShowScheduler + CutlessFinalizer against the existing source database (Toonami.db) and appends the new chunk to channels.json.

This means:

  • The watchdog needs Toonami.db to be the SAME database it was built against — don't blow away Toonami.db between sessions unless you also want to lose the cursor state.
  • The watchdog needs the source media (mounted under /app/anime, /app/bump, etc.) to still be available — if you unmount or remove episodes from your media library, future extensions will be smaller or fail.
  • The watchdog fires whether or not a client is currently streaming. Even with no Plex client connected, the channel grows on wall-clock time.

Override the lead time via env if you want a different runway buffer:

environment:
  - INFINITE_EXTEND_LEAD_MS=21600000  # 6 hours, in ms

Network Configuration

Internal Communication

When running multiple containers, use internal networking:

networks:
  default:
    name: toonami-network

services:
  commercialbreaker:
    networks:
      - default
    environment:
      - DIZQUETV_URL=http://dizquetv:8000
      - PLEX_URL=http://plex:32400

  dizquetv:
    networks:
      - default

  plex:
    networks:
      - default

External Access

services:
  commercialbreaker:
    ports:
      - "8081:8081"                     # Web interface (Absolution)
      - "8083:8083"                     # ComBreakDirect streaming server
    # Or bind to specific interface:
    # ports:
    #   - "192.168.1.100:8081:8081"
    #   - "192.168.1.100:8083:8083"

Accessing Services

Once the container is running, access the following URLs:

Absolution WebUI (Main Interface):

  • URL: http://localhost:8081
  • Purpose: Main application interface for managing Toonami channel creation

ComBreakDirect WebUI (Quick Links):

  • Landing Page: http://localhost:8083/
    • Setup instructions with copy buttons for tuner, playlist, and guide URLs
    • Plex, Jellyfin, and direct streaming configuration notes

ComBreakDirect Streaming Endpoints:

  • M3U8 Playlist: http://localhost:8083/playlist.m3u8
  • XMLTV Guide: http://localhost:8083/api/xmltv.xml
  • Continuous MPEG-TS Stream: http://localhost:8083/video/channel/1 (replace 1 with channel number)
  • HDHomeRun Discovery: http://localhost:8083/discover.json

Network Access: If accessing from other machines on the network, replace localhost with the Docker host's IP address (e.g., http://192.168.1.100:8083/).


Security Considerations

File Permissions

# Ensure Docker daemon can access folders
sudo chown -R 1000:1000 /path/to/anime
sudo chmod -R 755 /path/to/anime

# For working directory (needs write access)
sudo chmod -R 775 /path/to/working

User Mapping

services:
  commercialbreaker:
    user: "1000:1000"                   # Match host user
    # Or use environment variables:
    # user: "${UID}:${GID}"

Read-Only Mounts

volumes:
  - "${ANIME_FOLDER}:/app/anime:ro"     # Read-only anime
  - "${BUMPS_FOLDER}:/app/bump:ro"      # Read-only bumps
  - "${WORKING_FOLDER}:/app/working:rw" # Read-write working

Performance Optimization

Resource Limits

services:
  commercialbreaker:
    mem_limit: 8g                       # Memory limit
    cpus: 4                            # CPU limit
    ulimits:
      memlock:
        soft: -1
        hard: -1
    shm_size: 2g                       # Shared memory

Storage Optimization

services:
  commercialbreaker:
    volumes:
      - type: bind
        source: "${WORKING_FOLDER}"
        target: /app/working
        bind:
          propagation: cached           # Better performance

Tmpfs for Temporary Files

services:
  commercialbreaker:
    tmpfs:
      - /tmp:size=2G,uid=1000,gid=1000
      - /app/temp:size=5G

Health Checks and Monitoring

Health Check Configuration

services:
  commercialbreaker:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Logging Configuration

services:
  commercialbreaker:
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"
    # Or use external logging:
    # logging:
    #   driver: syslog
    #   options:
    #     syslog-address: "tcp://logserver:514"

Monitoring Commands

# View resource usage
docker stats commercialbreaker

# Monitor logs in real-time
docker logs -f commercialbreaker

# Check health status
docker inspect --format='{{.State.Health.Status}}' commercialbreaker

# Container details
docker inspect commercialbreaker

Troubleshooting

Common Issues

Container won't start:

# Check logs
docker logs commercialbreaker

# Verify environment
docker compose config

# Test volume mounts
docker run --rm -v "${ANIME_FOLDER}:/test" alpine ls -la /test

Permission denied errors:

# Fix ownership
sudo chown -R $(id -u):$(id -g) /path/to/working

# Check SELinux/AppArmor
ls -laZ /path/to/working

Memory issues:

# Increase memory limit
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Monitor memory usage
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Container Shell Access

# Access running container
docker exec -it commercialbreaker /bin/bash

# Run temporary debug container
docker run --rm -it \
  -v "${ANIME_FOLDER}:/app/anime" \
  tim000x3/commercial-breaker:latest \
  /bin/bash

Backup and Recovery

Database Backup

# Backup database
docker cp commercialbreaker:/app/data/Toonami.db ./backup/

# Automated backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker cp commercialbreaker:/app/data/Toonami.db ./backups/Toonami_${DATE}.db

Configuration Backup

# Backup entire configuration
tar -czf commercialbreaker_config_$(date +%Y%m%d).tar.gz \
  .env docker-compose.yml data/ logs/

Recovery

# Stop container
docker compose down

# Restore database
cp ./backup/Toonami.db ./data/

# Restart
docker compose up -d

Integration with External Services

Reverse Proxy (Nginx)

server {
    listen 80;
    server_name commercialbreaker.local;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SSL with Let's Encrypt

services:
  commercialbreaker:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.commercialbreaker.rule=Host(`commercialbreaker.yourdomain.com`)"
      - "traefik.http.routers.commercialbreaker.tls.certresolver=letsencrypt"

Development Setup

Local Development

services:
  commercialbreaker-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app                          # Mount source code
      - "${ANIME_FOLDER}:/app/anime"
    ports:
      - "8081:8081"
      - "5678:5678"                     # Debug port
    environment:
      - FLASK_ENV=development
      - DEBUG=true

Multi-Architecture Builds

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 -t commercialbreaker:latest .

# Push multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 -t user/commercialbreaker:latest --push .

Production Deployment

Docker Swarm

version: '3.8'

services:
  commercialbreaker:
    image: tim000x3/commercial-breaker:latest
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    networks:
      - toonami-network

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: commercialbreaker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: commercialbreaker
  template:
    metadata:
      labels:
        app: commercialbreaker
    spec:
      containers:
      - name: commercialbreaker
        image: tim000x3/commercial-breaker:latest
        ports:
        - containerPort: 8081
        volumeMounts:
        - name: anime-storage
          mountPath: /app/anime
        - name: working-storage
          mountPath: /app/working
      volumes:
      - name: anime-storage
        persistentVolumeClaim:
          claimName: anime-pvc
      - name: working-storage
        persistentVolumeClaim:
          claimName: working-pvc

For more information: