teto_ai/docs/setup.md

Setup and Installation Guide

This guide will walk you through setting up the Discord Teto Bot for video recording functionality.

📋 Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows with WSL2
• Docker: Version 20.10+ and Docker Compose v2+
• Disk Space: Minimum 2GB for container, additional space for recordings
• Memory: 4GB RAM recommended (2GB minimum)
• Network: Stable internet connection for Discord API

Discord Requirements

• Discord account with user token
• Server permissions to join voice channels
• Voice channel access where you want to record

Development Prerequisites (Optional)

• Node.js: Version 20+ for local development
• Git: For version control and cloning repository
• Text Editor: VS Code, Vim, or your preferred editor

🔧 Installation

Step 1: Clone Repository

git clone <your-repository-url>
cd discord_teto

Step 2: Environment Configuration

Create environment variables for your Discord token:

# Method 1: Export in terminal session
export USER_TOKEN="your_discord_user_token_here"

# Method 2: Create .env file (recommended)
echo "USER_TOKEN=your_discord_user_token_here" > .env

Getting Your Discord Token:

1. Open Discord in web browser
2. Press F12 to open Developer Tools
3. Go to Network tab
4. Refresh Discord
5. Look for requests to discord.com/api
6. Find Authorization header starting with your token

⚠️ Security Warning: Never share your Discord token publicly or commit it to version control.

Step 3: Directory Setup

Create the output directory for recordings:

mkdir -p output
chmod 755 output

This directory will be mounted into the Docker container to persist recordings.

Step 4: Docker Container Setup

Production Setup

# Build and start the container
docker compose up --build

# Or run in background
docker compose up -d --build

Development Setup (with live reload)

# Use development compose file
docker compose -f docker-compose.dev.yml up --build

# Or with live logs
docker compose -f docker-compose.dev.yml up --build --no-deps

Step 5: Verify Installation

1. Check container status:

   docker compose ps
   

   Should show teto_ai container as running.

2. Check logs:

   docker compose logs -f
   

   Should show bot connecting to Discord successfully.

3. Test basic functionality:

   • Send a DM to the bot containing "teto"
   • Bot should respond: "I'm here! What do you need?"

4. Test video recording:

   • Join a Discord voice channel
   • Type xbox record that in any text channel
   • Bot should join and start recording

🔍 Configuration Options

Environment Variables

Create a .env file in the project root:

# Required
USER_TOKEN=your_discord_user_token

# Optional
BOT_CLIENT_ID=your_bot_application_id
BOT_CLIENT_SECRET=your_bot_secret
BOT_REDIRECT_URI=https://your-domain.com/auth/callback

# Recording Settings (optional)
RECORDING_TIMEOUT=30000
MAX_RECORDING_DURATION=300000
OUTPUT_DIRECTORY=/tmp/output

Docker Compose Customization

Modify docker-compose.yml for your needs:

version: "3.8"
services:
  teto_ai:
    build: .
    container_name: teto_ai
    restart: unless-stopped
    volumes:
      - ./output:/tmp/output          # Recording output
      - ./logs:/opt/bot/logs          # Optional: persistent logs
    environment:
      - USER_TOKEN=${USER_TOKEN}
    ports:
      - "5901:5901"                   # VNC port (optional)
      - "3000:3000"                   # Web interface port (optional)
    tmpfs:
      - /tmp:size=512M                # Temporary processing space

Video Recording Settings

Modify src/config/videoConfig.js to customize recording behavior:

export const VIDEO_CONFIG = {
  // Timing
  AUTO_STOP_TIMEOUT: 30_000,        // 30 seconds
  MAX_RECORDING_DURATION: 300_000,  // 5 minutes
  PROCESSING_DELAY: 2000,           // 2 seconds

  // File settings
  OUTPUT_DIR: "/tmp/output",
  VIDEO_EXTENSION: ".mkv",
  
  // Voice settings
  VOICE_SETTINGS: {
    selfMute: true,
    selfDeaf: false,
    selfVideo: false,
  }
};

🔒 Security Considerations

Token Security

• Store tokens in environment variables, never in code
• Use .env files for local development (add to .gitignore)
• Consider using Docker secrets for production deployments
• Rotate tokens regularly

Container Security

• Bot runs as non-root user inside container
• Limited system capabilities (only SYS_ADMIN for Discord GUI)
• Isolated filesystem with specific volume mounts
• No network access beyond Discord API requirements

File Permissions

# Ensure proper ownership of output directory
sudo chown -R $(id -u):$(id -g) ./output/

# Set appropriate permissions
chmod 755 ./output/
chmod 644 ./output/*.mkv  # For recorded files

🐛 Troubleshooting Setup Issues

Common Installation Problems

1. Docker not found

# Install Docker (Ubuntu/Debian)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

# Verify installation
docker --version
docker compose version

2. Permission denied errors

# Fix Docker permissions
sudo usermod -aG docker $USER
newgrp docker

# Fix output directory permissions
sudo chown -R $(id -u):$(id -g) ./output/

3. Container fails to start

# Check logs
docker compose logs

# Common issues:
# - Invalid USER_TOKEN
# - Port conflicts (5901, 3000)
# - Insufficient disk space
# - Missing environment variables

4. Bot doesn't connect to Discord

• Verify USER_TOKEN is correct and not expired
• Check Discord API status
• Ensure network connectivity
• Check for Discord token rate limiting

Development Setup Issues

1. Node.js version mismatch

# Install Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js 20
nvm install 20
nvm use 20

2. Native dependency compilation errors

# Install build tools (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential python3-dev

# Install build tools (macOS)
xcode-select --install

# Clear and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

📊 Monitoring and Health Checks

Container Health

# Check container status
docker compose ps

# View resource usage
docker stats teto_ai

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

Recording Status

# Check output directory
ls -la ./output/

# Monitor disk usage
du -sh ./output/

# Check recent recordings
find ./output -name "*.mkv" -mtime -1 -ls

Discord Bot Status

Use the teto status command in Discord to check:

• Active recordings count
• File storage information
• Bot uptime
• Container status

🔄 Updates and Maintenance

Updating the Bot

# Pull latest changes
git pull origin main

# Rebuild and restart container
docker compose down
docker compose up --build -d

# Verify update
docker compose logs -f

Cleaning Up

# Stop and remove containers
docker compose down

# Remove old images
docker system prune -a

# Clean old recordings (optional)
find ./output -name "*.mkv" -mtime +30 -delete

📞 Getting Help

If you encounter issues during setup:

1. Check the logs: docker compose logs -f
2. Verify prerequisites: Ensure Docker, tokens, and permissions are correct
3. Consult troubleshooting: See troubleshooting.md
4. Review architecture: Check architecture.md for system understanding

🎯 Next Steps

After successful installation:

1. Test all commands: Try each bot command to ensure functionality
2. Review configuration: Customize settings in src/config/videoConfig.js
3. Set up monitoring: Implement log aggregation and health checks
4. Plan backups: Set up regular backups of recordings and configuration
5. Read documentation: Familiarize yourself with all available features

For detailed usage instructions, see commands.md and video-recording.md.