Index

Welcome to the Tux Administration Guide! This section covers everything you need to deploy, configure, and operate your own Tux instance.

Who Is This For?

This guide is for:

Self-hosters running their own Tux instance
System administrators deploying Tux for their community
DevOps engineers managing Tux in production
Server administrators configuring advanced settings

If you're just using Tux in a server, see the User Guide instead.

🚀 Deployment

Choose your deployment method:

Docker Compose - Recommended for most users
VPS with Systemd - Bare metal deployment
Cloud Platforms - Railway, DigitalOcean, etc.

⚙️ Setup

Initial setup guides:

Discord Bot Token - Create your Discord application
Database Setup - Configure PostgreSQL
Environment Variables - Configure .env
Config Files - TOML/YAML/JSON configuration
First Run - Starting Tux for the first time

🔧 Configuration

Configure your instance:

Configuration Overview - Understanding the config system
Bot Settings - Prefix, activity, presence
Guild Setup - Per-server configuration
Permissions - Set up permission ranks
Features - Enable/disable features
Advanced - Sentry, InfluxDB, plugins

🗄️ Database

Manage your database:

PostgreSQL Setup - Database configuration
Migrations - Running and managing migrations
Backups - Backup strategies
Adminer - Web UI for database management

🔍 Operations

Day-to-day operations:

Logging - Log management and rotation
Monitoring - Health checks and metrics
Updating - Keep Tux up to date
Troubleshooting - Common issues and solutions
Performance - Optimization and scaling

🔒 Security

Secure your deployment:

Best Practices - Security hardening
Token Security - Protecting sensitive data
Firewall - Network security

Quick Start

New to self-hosting? Start here:

1. Choose Deployment Method

Docker Compose (Recommended)

Easiest to set up
Includes PostgreSQL and Adminer
Automatic updates
Works on Linux, macOS, Windows

VPS Deployment

Full control
Better for production
Requires Linux knowledge

2. Get Prerequisites

Discord bot application
PostgreSQL database
Server or cloud instance

3. Deploy

Follow the deployment guide for your chosen method.

4. Configure

Set up your instance with environment variables and config files.

5. Start Using

Invite Tux to your server and run /config wizard.

Common Admin Tasks

Updating Tux

# Docker Compose
git pull
docker compose up -d --build
docker compose exec tux uv run db push

# Systemd
git pull
uv sync
uv run db push
sudo systemctl restart tux

Full Update Guide →

Viewing Logs

# Docker Compose
docker compose logs -f tux

# Systemd
journalctl -u tux -f

Logging Guide →

Database Backups

# Create backup
docker compose exec tux-postgres pg_dump -U tuxuser tuxdb > backup.sql

# Restore backup
docker compose exec -T tux-postgres psql -U tuxuser tuxdb < backup.sql

Backup Guide →

Checking Health

# Check bot status
docker compose ps

# Check database
docker compose exec tux uv run db health

# View metrics (if configured)
curl http://localhost:9090/metrics

Monitoring Guide →

Configuration Overview

Tux supports multiple configuration sources with priority:

Environment Variables (highest priority)
Config File (TOML/YAML/JSON)
Default Values (lowest priority)

Environment Variables (`.env`)

Required settings:

# Discord
BOT_TOKEN=your_token_here

# Database
POSTGRES_HOST=tux-postgres
POSTGRES_PORT=5432
POSTGRES_DB=tuxdb
POSTGRES_USER=tuxuser
POSTGRES_PASSWORD=secure_password

# Environment
ENVIRONMENT=production
DEBUG=false

Full Reference →

Config File (`config/config.toml`)

Optional but recommended:

[bot_info]
prefix = "$"
activity = "with Linux"

[features]
xp_enabled = true
starboard_enabled = true

Config File Guide →

System Requirements

Minimum Requirements

CPU: 1 core
RAM: 512 MB
Storage: 2 GB
OS: Linux, macOS, or Windows (with Docker)
Database: PostgreSQL 12+
Python: 3.13+ (if not using Docker)

Recommended for Production

CPU: 2+ cores
RAM: 2 GB
Storage: 10 GB (with backups)
OS: Linux (Ubuntu 22.04+ or Debian 12+)
Database: PostgreSQL 15+ (managed service recommended)
Network: Static IP or domain name

For Large Servers (1000+ members)

CPU: 4+ cores
RAM: 4+ GB
Storage: 20+ GB
Database: Dedicated PostgreSQL instance
Network: CDN for media (if applicable)
Monitoring: Sentry, Grafana, Prometheus

Architecture Overview

Tux consists of:

Bot Process: Main Discord bot (Python)
Database: PostgreSQL for persistent data
Cache: In-memory caching (optional Redis)
Logs: Structured logging with Loguru
Monitoring: Optional Sentry for errors
Metrics: Optional InfluxDB for performance

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Discord   │◄────►│  Tux Bot     │◄────►│ PostgreSQL  │
│     API     │      │  (Python)    │      │  Database   │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │   Sentry     │
                     │  (Optional)  │
                     └──────────────┘

Deployment Comparison

Feature	Docker Compose	VPS/Systemd	Cloud Platform
Ease of Setup	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
Control	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
Cost	Free (if you have server)	Free to low	Low to medium
Maintenance	Low	Medium	Very low
Scalability	Good	Excellent	Excellent
Recommended For	Most users	Advanced users	Quick start

Detailed Comparison →

Security Checklist

Before going to production:

[ ] Use strong database password
[ ] Enable firewall (UFW or similar)
[ ] Set up SSL/TLS for web interfaces
[ ] Configure log rotation
[ ] Set up automated backups
[ ] Use .env file with 600 permissions
[ ] Never commit secrets to version control
[ ] Enable Sentry for error monitoring
[ ] Configure rate limiting (if public)
[ ] Set up monitoring and alerts
[ ] Document your setup
[ ] Test disaster recovery process

Security Guide →

Monitoring & Alerts

What to Monitor

Bot uptime - Is the bot running?
Discord connection - Connected to Discord API?
Database health - Can connect to database?
Error rates - Are there unusual errors?
Resource usage - CPU, RAM, disk
Response times - Command latency

Recommended Tools

Sentry - Error tracking and performance
UptimeRobot - Uptime monitoring (free tier)
Grafana + Prometheus - Advanced metrics (optional)
InfluxDB - Time-series metrics (optional)