First Run

Previous Next

Start Tux for the first time and verify everything works.

Prerequisites Checklist

Before starting Tux, ensure you have:

  • [x] Discord bot token obtained
  • [x] PostgreSQL database created
  • [x] .env file configured
  • [x] Config file created (optional)
  • [x] 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

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

  1. Database Connection

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

  1. Bot Initialization

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

  1. Discord Connection

text 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
  4. Review Security - Harden your deployment

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

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

Community Support

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

Config Files Index