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:
```bash
docker-compose -f docker-compose.dev.yml up --build
```

For production:
```bash
docker-compose up --build
```

### 2. Verify Audio Dependencies

After container starts, you can verify FFmpeg installation:
```bash
# 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
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
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
```yaml
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
```bash
# 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