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 restartsDB_DIR: Internal database directory (defaults to/data)DB_PATH: Internal database path (defaults to/data/Toonami.db)_pre_rendered_breaksfolder: 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.pysubprocess (launched bystart.sh— the canonical Docker CBD instance): writes to/app/combreak_direct_data/channels.jsonbecause it doesn't pass--dockerinsys.argv. This path is in the container's writable layer, NOT a bind-mounted volume, so adocker compose down+upcycle wipes it.- Absolution thread fallback (
_ensure_combreakdirect_serverinsidemain.py --webui --docker): writes to/app/working/combreak_direct/channels.json, which IS bind-mounted via${WORKING_FOLDER}:/app/workingand 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.dbbetween 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(replace1with 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:
- Configuration Reference - Environment variables
- Troubleshooting - Common issues
- Architecture Overview - System design