# 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 is strongly recommended for GPU support. Windows with WSL2 is possible.
- **GPU**: NVIDIA GPU with 8GB+ VRAM is required for local model hosting.
- **Docker**: Version 20.10+ and Docker Compose v2+.
- **Disk Space**: 20GB+ SSD for models and container images.
- **Memory**: 16GB+ RAM recommended.
- **Network**: Local network for inter-service communication.

### Discord Requirements
- Discord account with user token.
- Server permissions to join voice channels.
- Voice channel access where you want to record.

### Local AI Requirements
- **LLM/VLM Model**: A downloaded language model compatible with `vLLM` (e.g., from Hugging Face).
- **TTS Voice Model**: A downloaded `Piper` voice model.
- **STT Model**: A downloaded `Whisper` model.

### 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 and local AI endpoints:

```bash
# Method 1: Export in terminal session
export USER_TOKEN="your_discord_user_token_here"
export VLLM_ENDPOINT="http://localhost:8000/v1"
export WYOMING_HOST="localhost"
export WYOMING_PORT="10300"

# Method 2: Create .env file (recommended)
echo "USER_TOKEN=your_discord_user_token_here" > .env
echo "VLLM_ENDPOINT=http://localhost:8000/v1" >> .env
echo "WYOMING_HOST=localhost" >> .env
echo "WYOMING_PORT=10300" >> .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. The bot operates on a user token and has the same permissions as your user.

### Step 3: Model & Directory Setup

1. **Create Directories**
   Create directories for recordings and for your AI models.
   ```bash
   mkdir -p output models/piper models/whisper models/llm
   chmod 755 output models
   ```
   This `models` directory will be mounted into your AI service containers.

2. **Download AI Models**
   - **Language Model**: Download your chosen GGUF or other `vLLM`-compatible model and place it in `models/llm`.
   - **Voice Model (Piper)**: Download a `.onnx` and `.json` voice file for Piper and place them in `models/piper`.
   - **Speech-to-Text Model (Whisper)**: The Whisper service will download its model on first run, or you can pre-download it.

This directory will be mounted into the Docker container to persist recordings and provide models to the AI services.

### Step 4: Local AI Stack & Bot Setup

This project uses a multi-container Docker setup for the bot and its local AI services. Your `docker-compose.yml` file should define services for:
- `teto_ai`: The bot itself.
- `vllm-openai`: The language model server, providing an OpenAI-compatible endpoint.
- `wyoming-piper`: The Text-to-Speech (TTS) service.
- `wyoming-whisper`: The Speech-to-Text (STT) service.

Below are sanitized, production-ready examples for these services. For full configuration details and explanations, please see the [Docker Compose Examples](docker-compose-examples.md) guide.

#### Production Setup
```bash
# Build and start all containers
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 to configure the bot and its connections to the local AI services:

```env
# Required: Discord Token
USER_TOKEN=your_discord_user_token

# Required: Local AI Service Endpoints
VLLM_ENDPOINT="http://vllm:8000/v1" # Using Docker service name
VLLM_MODEL="mistralai/Mistral-7B-Instruct-v0.2" # Model served by vLLM

WYOMING_HOST="wyoming" # Using Docker service name
WYOMING_PORT="10300"
PIPER_VOICE="en_US-lessac-medium" # Voice model for Piper TTS

# 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

### Data Privacy & Security
- **100% Local Processing**: All AI processing, including conversations, voice, and images, happens locally. No data is sent to external third-party services.
- **Token Security**: Your Discord token should still be kept secure in a `.env` file or Docker secrets. Never commit it to version control.
- **Network Isolation**: The AI services (`vLLM`, `Wyoming`) can be configured to only be accessible within the Docker network, preventing outside access.

### Container Security
- The bot and AI services run as non-root users inside their respective containers.
- Filesystem access is limited via specific volume mounts for models and output.

### 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

### Local AI Service Issues

**1. vLLM Container Fails to Start**
```bash
# Check vLLM logs for errors
docker compose logs vllm

# Common issues:
# - Insufficient GPU VRAM for the selected model.
# - Incorrect model path or name.
# - CUDA driver issues on the host machine.
# - Forgetting to build with --pull to get the latest base image.
```

**2. Wyoming Service Not Responding**
```bash
# Check Wyoming protocol server logs
docker compose logs wyoming

# Common issues:
# - Incorrect path to Piper voice models.
# - Port conflicts on the host (port 10300).
# - Whisper model download failure on first run.
```

**3. Teto Bot Can't Connect to AI Services**
- Verify service names in your `.env` file match the service names in `docker-compose.yml` (e.g., `http://vllm:8000/v1`).
- Ensure all containers are on the same Docker network.
- Use `docker compose ps` to see if all containers are running and healthy.

### 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 status of all containers (bot, vllm, wyoming)
docker compose ps

# View resource usage for all services
docker stats

# Monitor logs for a specific service in real-time
docker compose logs -f vllm
docker compose logs -f wyoming
docker compose logs -f teto_ai
```

### GPU Resource Monitoring
```bash
# Monitor GPU VRAM and utilization on the host machine
watch -n 1 nvidia-smi
```

### 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).