home / selfhost / install / first-run

First Run Instructions¶

Start Tux for the first time and verify everything works.

Prerequisites Checklist¶

Before starting Tux, ensure you have:

• Discord bot token obtained
• PostgreSQL database created
• .env file configured
• Config file created (optional)
• Dependencies installed (if not using Docker)

Starting Tux¶

Docker Compose¶

# Start all services
docker compose up -d

# View logs
docker compose logs -f tux

Local/VPS¶

# Ensure dependencies are installed
uv sync

# Run migrations
uv run db push

# Start bot
uv run tux start

What to Expect¶

Startup Sequence¶

1. Configuration Loading

Loading configuration...
✓ Environment variables loaded
✓ Config file loaded

1. Database Connection

Connecting to database...
✓ Database connected
✓ Running migrations...

1. Bot Initialization

Initializing bot...
✓ Loading cogs...
✓ Syncing commands...

1. Discord Connection

Connecting to Discord...
✓ Logged in as Tux#1234
✓ Ready!

Success Indicators¶

✅ Bot is ready log message
✅ Bot shows as online in Discord
✅ No error messages in logs
✅ Commands respond (/ping works)

Initial Configuration¶

1. Verify Bot is Online¶

In Discord, check:

• Bot appears in member list
• Green online status
• No error badge

2. Test Basic Command¶

/ping

Should respond with latency and uptime.

3. Run Setup Wizard¶

/config wizard

Interactive setup for:

• Moderation channels
• Jail system
• Starboard
• XP roles
• Basic settings

4. Set Up Permissions¶

/config rank init
/config role assign 3 @Moderators
/config role assign 5 @Admins

5. Test Moderation¶

/warn @TestUser Test warning
/cases

Verify case system works.

Troubleshooting First Run¶

Bot Won't Start¶

Check logs for specific error:

# Docker
docker compose logs tux

# Systemd
sudo journalctl -u tux -f

# Local
# Error appears in terminal

Common causes:

"Invalid Token" Error¶

discord.errors.LoginFailure: Improper token has been passed

Solution:

• Verify BOT_TOKEN in .env is correct
• No extra spaces or quotes
• Token is from Bot tab, not OAuth2 secret
• Reset token if unsure

"Database Connection Failed"¶

asyncpg.exceptions.InvalidCatalogNameError: database "tuxdb" does not exist

Solution:

• Create database: createdb tuxdb
• Check POSTGRES_* variables in .env
• Verify PostgreSQL is running
• Test connection: psql -h localhost -U tuxuser -d tuxdb

"Permission Denied" (Database)¶

asyncpg.exceptions.InsufficientPrivilegeError

Solution:

sudo -u postgres psql << EOF
GRANT ALL PRIVILEGES ON DATABASE tuxdb TO tuxuser;
\c tuxdb
GRANT ALL ON SCHEMA public TO tuxuser;
EOF

"Missing Intents"¶

Privileged intent ... is not enabled

Solution:

• Go to Discord Developer Portal
• Bot tab → Enable "Server Members Intent"
• Bot tab → Enable "Message Content Intent"
• Restart bot

Bot Starts But Shows Offline¶

Causes:

• Token is invalid
• Network connectivity issues
• Discord API issues

Solutions:

1. Check token is correct
2. Verify internet connection
3. Check Discord API status: status.discord.com
4. Review bot logs for connection errors

Commands Don't Work¶

Test slash commands:

/ping
/help

If not working:

1. Wait 1-2 minutes (Discord sync delay)
2. Check bot has applications.commands scope
3. Run /dev sync_tree (if you have permission)
4. Re-invite bot with correct scopes

Test prefix commands:

$ping
$help

If not working:

1. Check prefix is correct ($ by default)
2. Verify Message Content Intent is enabled
3. Check bot has Read Messages permission

Migration Errors¶

alembic.util.exc.CommandError

Solutions:

# Check migration status
uv run db status

# Apply migrations
uv run db push

# If corrupted, reset and retry
uv run db reset

Post-Startup Checks¶

Verify Core Features¶

# 1. Bot responding
/ping                               # ✓ Should respond

# 2. Database working
/snippet test_snippet               # Create test snippet first

# 3. Permissions working
/config rank                        # ✓ Should show ranks

# 4. Moderation working
/warn @TestUser Test                # ✓ Creates case

# 5. Check cases
/cases                              # ✓ Shows test case

Check Logs¶

Look for warnings or errors:

# Docker
docker compose logs tux | grep -E "ERROR|WARNING"

# Systemd
sudo journalctl -u tux | grep -E "ERROR|WARNING"

Monitor Resources¶

# Docker
docker stats tux

# System
htop
free -h
df -h

Configuration Verification¶

Check Loaded Config¶

Bot logs show loaded configuration on startup:

Configuration loaded from:
  - .env file
  - config.toml
  - Defaults

Verify Settings¶

/config                             # View current config

Should show your configured settings.

Next Steps¶

After successful first run:

1. Configure Features - Enable/disable features
2. Set Up Backups - Protect your data
3. Configure Monitoring - Watch for issues

Running in Background¶

Background with Docker Compose¶

Already runs in background with -d flag:

docker compose up -d

Background with Systemd¶

sudo systemctl enable tux           # Start on boot
sudo systemctl start tux            # Start now

Screen/Tmux (Not Recommended)¶

For temporary deployments only:

# Screen
screen -S tux
uv run tux start
# Ctrl+A, D to detach

# Tmux
tmux new -s tux
uv run tux start
# Ctrl+B, D to detach

Use systemd instead for production!

Logs Location¶

Docker¶

docker compose logs tux             # View logs

Systemd¶

journalctl -u tux -f                # Follow logs

Local Development¶

Logs output to stdout/stderr and optionally to files in logs/.

Need Help?¶

Common Issues¶

• Troubleshooting Guide - Common problems
• Database Issues - Database-specific

Community Support¶

• Discord Server - Ask in #self-hosting
• GitHub Issues - Report bugs

Congratulations! Tux is now running. Head to Configuration to customize your instance.