Self Hosting Guide

Vör is open-source software that you can host on your own infrastructure. This guide covers everything you need to know about running your own instance of Vör.

Contents

• Why Self-Host?
• Prerequisites
• Quick Setup
• Detailed Configuration
• Database Setup
• Web Dashboard (Optional)
• Production Deployment
• Security Best Practices
• Troubleshooting
• Getting Help
• Support & Maintenance
• Bot Administration

Why Self-Host?

Benefits

• Full Control: Complete control over your bot instance
• Customization: Modify code and features as needed
• Privacy: Keep all data on your own servers
• No Dependencies: Not reliant on external hosting services
• Cost Effective: Pay only for your infrastructure

Considerations

• Technical Knowledge: Requires server administration skills
• Maintenance: You’ll need to handle updates and security
• Infrastructure: Need reliable hosting with good uptime
• Support: Community support only (no official SLA)

Prerequisites

Hardware Requirements

• CPU: 1+ core (2+ recommended)
• RAM: 512MB minimum (1GB+ recommended)
• Storage: 1GB+ for bot files and databases
• Network: Stable internet connection

Software Requirements

• Operating System: Linux, Windows, or macOS
• Python: Version 3.13 (recommended) or 3.12+
• Git: For cloning the repository
• SQLite: Included with Python (used by most legacy modules)
• PostgreSQL: Version 16.x recommended (15.x acceptable, 14+ minimum) for Message Forensics (phase 1 migration)

Network Requirements

• Outbound HTTPS: For API calls (Discord, VirusTotal, etc.)
• Inbound TCP: Port for your web dashboard (optional)
• Discord Gateway: WebSocket connection to Discord

Quick Setup

1. Clone the Repository

git clone https://gitlab.com/pc-help-hub/vor
cd vor

2. Set Up Python Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Configure Environment

# Copy example environment file
cp bot_config/example_env bot_config/.env

# Edit with your settings
nano bot_config/.env  # or your preferred editor

4. Start the Bot

python main.py

Detailed Configuration

Discord Bot Setup

1. Create Discord Application
   • Go to Discord Developer Portal
   • Create a new application
   • Navigate to the “Bot” section
2. Configure Bot Permissions
   • Enable required intents:
     • ✅ Message Content Intent
     • ✅ Server Members Intent
   • Set bot permissions for your invite link
3. Get Bot Token
   • Copy the bot token from the “Bot” section
   • Add to your .env file: DISCORD_BOT_TOKEN=your_token_here

Environment Variables

Required Settings

# Discord bot token
DISCORD_BOT_TOKEN=your_bot_token_here

# Bot owner IDs (comma-separated)
BOT_OWNERS=123456789012345678,987654321098765432

# Bot prefix (default: !)
BOT_PREFIX=!

Optional Settings

# Debug mode
DEBUG_MODE=false

# Logging level
LOG_LEVEL=INFO

# Dashboard URL (if hosting web interface)
VOR_DASHBOARD_URL=https://your-domain.com

API Keys (as needed)

# Currency conversion
CURRENCY_API_KEY=your_currencybeacon_key

# Virus scanning
VT_API_KEY=your_virustotal_key

# Error logging webhook
WEBHOOK_ERROR=https://discord.com/api/webhooks/your/webhook

Database Setup

Vör currently uses a mixed database architecture:

• SQLite for most existing modules.
• PostgreSQL for Message Forensics (SelfPurgeIncident, IncidentChannel, ForensicMessage, RawDeleteEvent).

SQLite Database Files

Will auto-create, and don’t need any prior configuration or installation.
Examples:

• vor.db - Main bot data
• vor_modlogs.db - Moderation logs
• vor_economy.db - Economy data
• vor_notes.db - User notes
• vor_reputation.db - Reputation data
• vor_tiers.db - XP/levels data

PostgreSQL 16 Setup (Ubuntu)

Quick Setup (Automated): Download and run the setup script:

wget https://gitlab.com/pc-help-hub/vor/-/raw/main/scripts/setup_postgresql_ubuntu.sh
chmod +x setup_postgresql_ubuntu.sh
./setup_postgresql_ubuntu.sh

Manual Setup: Run this on your Ubuntu host to install PostgreSQL 16 and create the role / database.

#!/usr/bin/env bash
set -euo pipefail

sudo apt update
sudo apt install -y postgresql-16 postgresql-client-16 postgresql-contrib

sudo systemctl enable postgresql
sudo systemctl start postgresql

sudo -u postgres psql -c "SELECT version();"

sudo -u postgres psql <<'SQL'
DO $$
BEGIN
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'vor_db_role') THEN
      CREATE ROLE vor_db_role LOGIN PASSWORD 'CHANGE_ME_STRONG_PASSWORD';
   END IF;
END
$$;

CREATE DATABASE vor_data_primary OWNER vor_db_role;
SQL

echo "PostgreSQL 16 setup complete. Update bot_config/.env with VOR_DATA_PG_* values."

Harden the postgres superuser (recommended):

After initial setup, set a strong password for the postgres superuser and reserve it for administrative tasks only.

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'REPLACE_WITH_LONG_RANDOM_PASSWORD';"

Optional checks:

• Ensure your app uses vor_db_role, not postgres
• Prefer scram-sha-256 for password auth in pg_hba.conf
• Restrict superuser access to local/admin workflows

PostgreSQL 16 Setup (Windows)

1. Install PostgreSQL 16.x (choose one method):

Using Winget:

winget install --id PostgreSQL.PostgreSQL.16 --exact --source winget

Using Chocolatey:

choco install postgresql16 -y

Download Official Installer:

Download the installer from https://www.postgresql.org/download/windows/
Run the installer

2. Open SQL Shell (psql) as the postgres superuser.

3. Run:

DO $$
BEGIN
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'vor_db_role') THEN
      CREATE ROLE vor_db_role LOGIN PASSWORD 'CHANGE_ME_STRONG_PASSWORD';
   END IF;
END
$$;

CREATE DATABASE vor_data_primary OWNER vor_db_role;

PowerShell alternative:

$env:PGPASSWORD = "YOUR_POSTGRES_ADMIN_PASSWORD"
psql -U postgres -h localhost -p 5432 -d postgres -c "DO \$\$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'vor_db_role') THEN CREATE ROLE vor_db_role LOGIN PASSWORD 'CHANGE_ME_STRONG_PASSWORD'; END IF; END \$\$;"
psql -U postgres -h localhost -p 5432 -d postgres -c "CREATE DATABASE vor_data_primary OWNER vor_db_role;"

Harden the postgres superuser (recommended):

The Windows installer asks you to set the postgres password during install. If it is weak, rotate it immediately:

ALTER USER postgres WITH PASSWORD 'REPLACE_WITH_LONG_RANDOM_PASSWORD';

Then keep postgres for admin-only actions and run Vor with vor_db_role in VOR_DATA_PG_*.

Message Forensics PostgreSQL Environment Variables

Add these to bot_config/.env:

VOR_DATA_PG_HOST=localhost
VOR_DATA_PG_PORT=5432
VOR_DATA_PG_DATABASE=vor_data_primary
VOR_DATA_PG_USER=vor_db_role
VOR_DATA_PG_PASSWORD=CHANGE_ME_STRONG_PASSWORD
# Optional. Set to require/true for SSL-enabled deployments.
VOR_DATA_PG_SSL=disable

There is an example at bot_config/example_env

Backup Strategy

# Create backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p backups
cp *.db backups/
cp bot_config/.env backups/
pg_dump -h localhost -p 5432 -U vor_db_role -d vor_data_primary > backups/vor_data_primary_$DATE.sql
tar -czf backups/vor_backup_$DATE.tar.gz backups/*.db backups/*.sql backups/.env

Web Dashboard (Optional)

Requirements

• Web Server: Nginx, Apache, or similar
• SSL Certificate: For HTTPS (Let’s Encrypt recommended)
• Domain: Pointed to your server

Setup Steps

1. Configure dashboard URL in .env
2. Set up reverse proxy
3. Obtain SSL certificate
4. Start dashboard service

Example Nginx Configuration

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Production Deployment

Process Management

# Using systemd
sudo nano /etc/systemd/system/vor.service

[Unit]
Description=Vör Discord Bot
After=network.target

[Service]
Type=simple
User=vor
WorkingDirectory=/path/to/vor
ExecStart=/path/to/vor/venv/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable vor
sudo systemctl start vor

Monitoring

• Logs: Check systemd logs with journalctl -u vor
• Health Checks: Monitor bot status via Discord
• Resource Usage: Monitor CPU/memory with htop or top

Updates

# Stop the bot
sudo systemctl stop vor

# Update code
git pull origin main

# Update dependencies
source venv/bin/activate
pip install -r requirements.txt

# Restart
sudo systemctl start vor

Security Best Practices

Bot Token Security

• Never commit tokens to version control
• Use environment variables, not config files
• Rotate tokens regularly
• Limit token permissions

Server Security

• Keep system updated: apt update && apt upgrade
• Use firewall: ufw enable
• Set up SSH key authentication
• Disable root login

Data Protection

• Regular database backups
• Encrypt sensitive data
• Secure API keys
• Monitor for unauthorized access

Troubleshooting

Bot Won’t Start

# Check Python version
python --version

# Check virtual environment
which python

# Check dependencies
pip list

# Check .env file
cat bot_config/.env

Connection Issues

• Verify Discord token is correct
• Check internet connectivity
• Review firewall settings
• Check Discord status page

Database Errors

• Ensure write permissions on database directory (SQLite files)
• Confirm PostgreSQL service is running and reachable
• Verify VOR_DATA_PG_* values in bot_config/.env
• Check available disk space

PostgreSQL Command Not Found (Windows)

If psql is not recognized after installation, PostgreSQL’s bin directory is not in your PATH:

Immediate workaround:

"C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres

Permanent fix — Add PostgreSQL to PATH:

1. Press Win+X, search for “Environment Variables”
2. Click “Edit the system environment variables”
3. Click “Environment Variables” button
4. Under “System variables”, select Path and click “Edit”
5. Click “New” and add: C:\Program Files\PostgreSQL\16\bin
6. Restart PowerShell and test with: psql --version

Alternative: Use pgAdmin 4 (web GUI included with PostgreSQL installation) instead of the command line.

Performance Issues

• Monitor resource usage
• Check for memory leaks
• Review log files for errors
• Consider upgrading hardware

Getting Help

Community Resources

• Documentation: Full Documentation
• Discord Server: Join Support Server
• GitLab Issues: Report bugs and request features

Developer Setup

For development and advanced configuration:

📚 Initial Setup Guide

This guide covers environment setup, dependency management, and development workflow.

Support & Maintenance

Regular Maintenance

• Weekly: Check logs for errors
• Monthly: Update dependencies and system packages
• Quarterly: Review security settings and backups

Community Support

• Join our Discord server for help
• Check documentation for common issues
• Contribute to the project on GitLab

Professional Services

For enterprise deployments or custom development, contact the development team.

---

Legal Notice

Self-hosting Vör is subject to the same license terms as the official distribution. Ensure compliance with Discord’s Terms of Service and applicable laws in your jurisdiction.

Bot Administration

The Bot Admin cog provides administrative tools for managing your Vör bot instance. This section covers the commands and features available for bot owners and authorized administrators.

Features

Bot Management

• Restart Command: Remotely restart the bot
• Update System: Pull latest changes from Git repository
• Status Monitoring: Check bot health and performance
• Cog Management: Load, unload, or reload individual cogs

Git Integration

• Repository Operations: Fetch, pull, and check repository status
• Commit Analysis: View changes in recent commits
• Branch Management: Switch between branches

Access Control

• Authorized Users: Configurable list of users who can use bot admin commands
• Authorized Servers: Restrict bot admin commands to specific servers
• Permission Validation: Multi-layer permission checking

System Tools

• File Operations: Backup and restore configuration files
• Log Management: Access and rotate log files
• Database Maintenance: Database backup and integrity checks

Commands

Command	Description	Access Level
/botadmin restart	Restart the bot	Bot Admin
/botadmin update	Update bot from repository	Bot Admin
/botadmin status	Check bot status	Bot Admin
/botadmin cogs	Manage loaded cogs	Bot Admin

Configuration

• Allowed User IDs: List of Discord user IDs with bot admin access
• Allowed Server IDs: List of server IDs where bot admin commands can be used

Security

This cog contains powerful commands that can affect bot operation. Access is strictly controlled and logged. Only configure trusted users as bot administrators.

Usage Notes

• Commands are restricted to prevent unauthorized access
• All actions are logged for audit purposes
• Use with caution as some operations can disrupt bot service