Mikolaj Wojciech Gorski 2e94820164 Updated the docs to focus on a local only stack instead of one relient on services like OpenAI, Eleven labs and so on.

2025-07-26 14:26:18 +02:00

12 KiB

Raw Blame History

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

git clone <your-repository-url>
cd discord_teto

Step 2: Environment Configuration

Create environment variables for your Discord token and local AI endpoints:

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

Open Discord in web browser
Press F12 to open Developer Tools
Go to Network tab
Refresh Discord
Look for requests to discord.com/api
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

Create Directories Create directories for recordings and for your AI models.
```
mkdir -p output models/piper models/whisper models/llm
chmod 755 output models
```
This models directory will be mounted into your AI service containers.
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 guide.

Production Setup

# Build and start all containers
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

Check container status:
```
docker compose ps
```
Should show teto_ai container as running.
Check logs:
```
docker compose logs -f
```
Should show bot connecting to Discord successfully.
Test basic functionality:
- Send a DM to the bot containing "teto"
- Bot should respond: "I'm here! What do you need?"
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:

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

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

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

# 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

# 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

# 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

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

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

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:

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

🎯 Next Steps

After successful installation:

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

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

12 KiB Raw Blame History