415 lines
No EOL
12 KiB
Markdown
415 lines
No EOL
12 KiB
Markdown
# 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). |