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

```bash
git clone <your-repository-url>
cd discord_teto
```

### Step 2: Environment Configuration

Create environment variables for your Discord token:

```bash
# 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:

```bash
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
```bash
# Build and start the container
docker compose up --build

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

#### Development Setup (with live reload)
```bash
# 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:**
   ```bash
   docker compose ps
   ```
   Should show `teto_ai` container as running.

2. **Check logs:**
   ```bash
   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:

```env
# 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:

```yaml
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:

```javascript
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
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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
```bash
# Check container status
docker compose ps

# View resource usage
docker stats teto_ai

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

### Recording Status
```bash
# 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
```bash
# 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
```bash
# 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](troubleshooting.md)
4. **Review architecture**: Check [architecture.md](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](commands.md) and [video-recording.md](video-recording.md).