🤖 TitanBot - Ultimate Discord Bot

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.

📚 Table of Contents

• 🌟 Features Overview
• 🚀 Quick Setup
• ⚙️ Manual Installation Steps
• 🗄️ Database System
• 🌐 Support Server
• 🏗️ Bot Architecture
• 🤝 Contributing

🌟 Features Overview

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

🛡️ Moderation & Administration Mass Actions - Bulk ban/kick capabilities User Notes - Keep detailed moderation records Case Management - View and track all mod actions 💰 Economy System Shop & Inventory - Buy and manage items Gambling - Risk it for rewards Pay System - Transfer money between users 🎮 Fun & Entertainment Random Facts - Learn something new Wanted Poster - Create fun wanted images Text Reversal - Reverse any text 🎫 Advanced Ticket System Claim & Priority - Staff ticket management Ticket Limits - Prevent spam Transcript System - Save ticket history � Server Stats Member Counter - Live member count channels Voice Counters - Track voice stats Dynamic Updates - Real-time channel updates 🎭 Reaction Roles Role Assignment - Self-assignable roles Emoji Selection - Reaction-based system Multi-role Support - Multiple role options

📊 Leveling & XP System XP Tracking - Automatic message-based XP Level Roles - Auto-assign roles by level Custom Configuration - Personalize leveling 🎉 Giveaways & Events Multiple Winners - Support multi-winner giveaways Auto Picking - Automatic winner selection Reroll System - Pick new winners if needed 🎂 Birthday System Birthday Tracking - Never miss a birthday Auto Announcements - Celebrate automatically Timezone Support - Accurate worldwide tracking 🔧 Utility Tools Report System - Report issues to staff Todo Lists - Personal task management First Message - Jump to channel's first message 👋 Welcome System Welcome Messages - Greet new members Auto Roles - Assign roles on join Custom Embeds - Personalized messages

🚀 Quick Setup (recommend)

📹 Video Tutorial

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

🐳 Docker Deployment (Recommended)

TitanBot is fully containerized for easy deployment.

Using Docker Compose

1. Clone the repository:

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

2. Configure environment variables: Create a .env file from .env.example and fill in your bot details and PostgreSQL credentials.

3. Start the containers:

   docker-compose up -d

This will start both the bot and a persistent PostgreSQL database.

Using GitHub Container Registry

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

docker pull ghcr.io/codebymitch/titanbot:main

⚙️ Manual Installation Steps

Prerequisites

• Node.js 18.0.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).

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. Test Database Connection

   npm run test-postgres

6. Start the Bot

   npm start

🗄️ Database System

TitanBot uses PostgreSQL as its primary database with intelligent fallback to memory storage:

PostgreSQL Features

• ACID Compliance: Reliable transactions and data integrity
• High Performance: Optimized queries and connection pooling
• Persistence: Data survives bot restarts and crashes
• Complex Queries: Advanced data analysis capabilities
• Scalability: Better performance for large datasets
• TTL Support: Automatic key expiration for temporary data
• Connection Management: Automatic reconnection with exponential backoff
• Automatic Schema Creation: Tables and indexes created on connection

Fallback System

• Memory Storage: Automatic fallback when PostgreSQL is unavailable
• Graceful Degradation: Bot continues functioning without database
• Backward Compatibility: Maintains existing API structure
• Zero Downtime: Seamless switching between database and memory

🏗️ Bot Architecture

Technology Stack

• Discord.js v14 - Modern Discord API wrapper
• Node.js 18+ - JavaScript runtime environment
• PostgreSQL - High-performance relational database
• Express.js - Web server for health checks
• Winston - Advanced logging system
• Node-cron - Scheduled task management

Bot Intents

TitanBot requires the following Discord intents:

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

Required Permissions

• 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

🤝 Contributing

We welcome contributions to TitanBot! Here's how you can help:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Development Guidelines

• Follow existing code style
• Add proper error handling
• Include documentation for new features
• Test with PostgreSQL and memory storage

📜 License

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

💌 Thank You

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

Made with ❤️

Last updated: April 2026