TitanBot is a powerful, feature-rich Discord bot designed to enhance your server experience with comprehensive moderation tools, engaging economy systems, utility features, and much more. Built with modern Discord.js v14 and PostgreSQL for optimal performance and data persistence.

• Features Overview
• Quick Setup
• Manual Installation Steps
• Support Server
• Required Bot Intents
• Contributing

TitanBot offers a complete suite of tools for Discord server management and community engagement:

For a detailed step-by-step setup guide, watch our comprehensive video tutorial: TitanBot Setup Tutorial

TitanBot is fully containerized for easy deployment.

1. Clone the repository:

   git clone https://github.com/codebymitch/TitanBot.git
   cd TitanBot

2. Configure environment variables:

   cp .env.example .env

   Set at minimum DISCORD_TOKEN, CLIENT_ID, and GUILD_ID. Docker Compose also reads POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB from .env (defaults: titanbot / password / titanbot).

3. Build and start the containers:

   docker compose up -d --build

4. Check status:

   docker compose ps
   curl http://localhost:3000/health

This starts the bot and PostgreSQL. The compose file sets POSTGRES_SSL=false and AUTO_MIGRATE=true for the bundled database. Music uses public Lavalink v4 nodes from lavalink/nodes.json by default.

Music uses Lavalink v4 via Riffy, similar to Musicify.

1. By default, the bot loads multiple public v4 SSL nodes from lavalink/nodes.json (sourced from lavalink.darrennathanael.com). Edit that file to add or remove nodes.
2. To self-host Lavalink instead, run docker compose --profile local-lavalink up -d and set single-node env vars in .env:

   LAVALINK_HOST=lavalink
   LAVALINK_PORT=2333
   LAVALINK_PASSWORD=youshallnotpass
   LAVALINK_SECURE=false

   Remove or rename lavalink/nodes.json so the bot falls back to those env vars.
3. Override nodes inline with LAVALINK_NODES (JSON array) or point at another file with LAVALINK_NODES_FILE.
4. Use /play <song> from a voice channel, or /join to connect without playing. Prefix shortcuts: join, np, leave, pause, resume, skip, stop, volume <0-100>, or music <subcommand>. Use /nowplaying and /queue for status; /music for loop, shuffle, seek, and other controls.

The bot is automatically published to GitHub Container Registry on every push to main.

docker pull ghcr.io/codebymitch/titanbot:main

• Node.js 20.10.0 or higher
• PostgreSQL server (recommended) or memory storage fallback
• Discord bot application with proper intents

1. Clone the Repository

   git clone https://github.com/codebymitch/TitanBot.git
   cd TitanBot

2. Install Dependencies

   npm install

3. Configure Environment Variables

   cp .env.example .env

   Edit .env with your configuration (only the following variables require configuration, leave remaining variables as default):

   # Discord Bot Configuration
   DISCORD_TOKEN=your_discord_bot_token_here
   CLIENT_ID=your_discord_client_id_here
   GUILD_ID=your_discord_guild_id_here
   
   # PostgreSQL Configuration (Primary Database)
   POSTGRES_URL=postgresql://postgres:yourpassword@localhost:5432/titanbot
   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   POSTGRES_DB=titanbot
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=yourpassword

   Production note:

   • NODE_ENV=production
   • LOG_LEVEL=warn for a clean production console (critical issues + startup status)
   • LOG_LEVEL=info if you want more detailed operational logs
   • If your chosen PORT is already used, TitanBot automatically tries the next port(s)

   Environment options reference:

   • NODE_ENV: development, production, test (any non-production value is treated as non-production)
   • LOG_LEVEL: error, warn, info, http, verbose, debug, silly
   • Accepted aliases for LOG_LEVEL in this bot: warns, warning, warnings → warn

   Recommended production .env (easy mode + default mode):

   NODE_ENV=production
   LOG_LEVEL=warn
   WEB_HOST=0.0.0.0
   PORT=3000
   PORT_RETRY_ATTEMPTS=5

   This gives clear startup/online status messages while keeping logs simple for non-technical operators. If port 3000 is busy, the bot tries the next available ports automatically (up to PORT_RETRY_ATTEMPTS).

Slash commands are registered globally on startup (via CLIENT_ID), so the bot works in every server it is invited to. GUILD_ID stays in the tutorial .env for setup steps but is not used for command registration.

Notes:

• Global slash commands may take up to about an hour to propagate on first deploy
• Each server has isolated data: config, economy, tickets, leveling, dashboards, warnings, etc. (all keys are scoped as guild:{guildId}:...)
• In the Discord Developer Portal, ensure your bot is not restricted to a single guild if you plan to invite it elsewhere
• Generate an OAuth2 invite URL from the Discord Developer Portal (OAuth2 → URL Generator, scopes: bot and applications.commands)

4. Setup PostgreSQL Database (Optional but recommended)

   # Create database and user
   createdb titanbot
   createuser titanbot
   psql -c "ALTER USER titanbot PASSWORD 'yourpassword';"
   psql -c "GRANT ALL PRIVILEGES ON DATABASE titanbot TO titanbot;"

5. Verify Database Setup

   npm run migrate:check

6. Start the Bot

   npm start

Note on database migrations: Schema tables and legacy key migrations run automatically on startup, somanaged hosts like **Railway** need no manual migration step — just deploy/restart. To disable auto-migration setAUTO_MIGRATE=false. You can still run a manual key migration locally with node scripts/migrate-keys.js --dry-run(preview) ornode scripts/migrate-keys.js`.

TitanBot requires the following Discord intents:

• Guilds
• Guild Messages
• Message Content
• Guild Members
• Guild Message Reactions
• Guild Voice States
• Direct Messages
• Bot
• Applications.commands

• View Channels
• Send Messages
• Embed Links
• Attach Files
• Read Message History
• Manage Messages
• Manage Channels
• Manage Roles
• Kick Members
• Manage Messages
• Ban Members
• Moderate Members
• Connect

TitanBot is released under the MIT License. See LICENSE for details.

Thank you for choosing TitanBot for your Discord server! We're constantly working to improve and add new features based on community feedback.

Last updated: May 2026