teto_ai/docs/docker.md

Docker Video Recording Setup

This document explains how to set up and use the video recording functionality in the Docker-containerized Teto bot.

Docker Environment Overview

The bot runs in a Docker container with the following key components:

• Container OS: Node.js 20 on Debian slim
• Video Processing: FFmpeg, PulseAudio, Opus libraries
• Encryption: libsodium for Discord voice encryption
• Output Volume: ./output:/tmp/output (host folder mounted to container)
• User Context: Runs as bot user (non-root)
• Display: Virtual X11 display with VNC access

Prerequisites

Host System Requirements

• Docker and Docker Compose installed
• Sufficient disk space in ./output/ directory for audio files
• Environment variables configured (USER_TOKEN, etc.)

Container Dependencies (Automatically Installed)

• ffmpeg - Video/audio processing and format conversion
• libopus0 & libopus-dev - Opus audio codec support
• libsodium23 & libsodium-dev - Encryption for Discord voice
• build-essential & libtool - For compiling native dependencies
• pulseaudio - Audio system management
• opusscript - Node.js Opus bindings (via npm)
• sodium - Native encryption library (via npm)

Setup Instructions

1. Build the Docker Image

For development with live reload:

docker-compose -f docker-compose.dev.yml up --build

For production:

docker-compose up --build

2. Verify Audio Dependencies

After container starts, you can verify FFmpeg installation:

# Enter the running container
docker exec -it teto_ai bash

# Check FFmpeg
ffmpeg -version

# Check output directory
ls -la /tmp/output

3. Test Voice Recording

1. Join a Discord voice channel
2. In any Discord text channel, type: xbox record that
3. The bot will join your voice channel and start video recording
4. Video files will be saved to ./output/ on your host system as .mkv files

File Storage Architecture

Host System:
./output/                           # Your project directory
├── recording-2024-01-15T14-30-45-123Z.mkv
├── recording-2024-01-15T14-31-00-456Z.mkv
└── ...

Docker Container:
/tmp/output/                        # Mounted volume (same files)
├── recording-2024-01-15T14-30-45-123Z.mkv
├── recording-2024-01-15T14-31-00-456Z.mkv
└── /tmp/                          # Temporary files (512MB tmpfs)
    └── (Video processing files - auto-deleted)

Commands Reference

Video Recording Commands

Command	Action	Container Behavior
xbox record that	Start video recording	Joins voice channel, creates /tmp/output/recording-*.mkv
stop recording	Stop recording	Finalizes video file, saves to mounted volume
xbox stop	Stop recording	Same as above
teto status	Show status	Reports container and host paths

Development Commands

# View container logs
docker-compose logs -f teto_ai

# Access container shell
docker exec -it teto_ai bash

# Restart container
docker-compose restart teto_ai

# Rebuild and restart
docker-compose down && docker-compose up --build

Troubleshooting

Container Issues

1. FFmpeg not found

# Check if FFmpeg is installed in container
docker exec -it teto_ai which ffmpeg
# Should return: /usr/bin/ffmpeg

2. Permission issues with output directory

# Check permissions on host
ls -la ./output/

# Fix permissions if needed
chmod 755 ./output/

3. Video processing fails

• Check container logs: docker-compose logs teto_ai
• Verify FFmpeg installation in container
• Ensure libsodium encryption libraries are installed
• Ensure sufficient disk space

Discord Connection Issues

1. Bot can't join voice channel

• Verify bot has Connect permission in Discord
• Check if bot is already in another voice channel
• Ensure discord.js-selfbot-v13 voice dependencies are working

2. No video/audio captured

• Confirm users are speaking during recording
• Check Discord voice activity settings
• Verify Opus and libsodium libraries are properly installed
• Ensure encryption dependencies are working

Volume Mount Issues

1. Files not appearing on host

# Verify volume mount in docker-compose
docker inspect teto_ai | grep -A 5 "Mounts"

# Should show: /tmp/output mounted to ./output

2. Container can't write to mounted volume

# Check ownership of host directory
ls -la ./output/

# May need to adjust ownership
sudo chown -R $(id -u):$(id -g) ./output/

Performance Considerations

Resource Usage

• CPU: Moderate to high usage during active video recording and processing
• Memory: ~100-200MB base + video/audio buffers
• Disk: ~15-30MB per minute of recorded video (MKV format with audio)
• Network: Standard Discord voice data reception

Container Limits

• tmpfs: 512MB allocated for temporary video processing
• Volume: Unlimited (depends on host disk space)
• Concurrent recordings: One per voice channel
• Encryption: Requires libsodium for Discord voice protocol

Development Tips

Live Development

When using docker-compose.dev.yml:

• Source code is mounted as volume for live reload
• Changes to src/events/messageCreate.js are automatically reflected
• No need to rebuild container for code changes

Debugging Video/Audio Issues

# Enter container and check video setup
docker exec -it teto_ai bash

# Test FFmpeg video functionality
ffmpeg -f lavfi -i testsrc2=duration=5:size=320x240:rate=30 test.mp4

# Check audio processing capabilities
ffmpeg -f lavfi -i sine=frequency=1000:duration=5 test.wav

# Verify Opus support
ffmpeg -codecs | grep opus

# Check libsodium installation
ldconfig -p | grep sodium

Container Health Checks

Add to your monitoring:

# Check if bot process is running
docker exec teto_ai ps aux | grep node

# Monitor output directory
watch -n 5 'ls -la ./output/'

# Check container resource usage
docker stats teto_ai

Security Notes

Container Security

• Bot runs as non-root user (bot)
• Limited system capabilities (SYS_ADMIN for Discord GUI)
• Isolated file system with specific volume mounts only

Video/Audio Data

• Recordings stored locally in mounted volume as MKV files
• No external transmission of video/audio data
• Files persist until manually deleted
• Consider implementing automatic cleanup for privacy
• Encryption handled by libsodium for Discord voice protocol

Production Deployment

Environment Variables

Ensure these are set in your deployment:

USER_TOKEN=your_discord_token
BOT_CLIENT_ID=your_bot_id
BOT_CLIENT_SECRET=your_bot_secret
BOT_REDIRECT_URI=https://your-domain.com/auth/callback

Docker Compose Production

version: "3.8"
services:
  teto_ai:
    build: .
    container_name: teto_ai
    restart: unless-stopped
    volumes:
      - ./output:/tmp/output
      - ./logs:/opt/bot/logs  # Optional: persistent logs
    environment:
      - USER_TOKEN=${USER_TOKEN}
      # ... other env vars

Monitoring

• Set up log aggregation for container logs
• Monitor disk usage of ./output/ directory
• Implement health checks for voice recording functionality
• Consider backup strategy for important recordings

Backup and Maintenance

Regular Maintenance

# Clean old recordings (example: older than 30 days)
find ./output -name "recording-*.mkv" -mtime +30 -delete

# Check container health
docker-compose ps
docker-compose logs --tail=100 teto_ai

# Update and rebuild
git pull
docker-compose down
docker-compose up --build -d

Backup Strategy

• Video files: Backup ./output/ directory regularly (MKV files can be large)
• Configuration: Version control Docker configs and environment files
• Logs: Archive container logs if needed for debugging