TitanBot: A Comprehensive Discord Bot with Moderation, Economy, and Music

Music, moderation, and economy in one Discord bot

TitanBot consolidates moderation, community engagement, and entertainment into one bot. The README describes it as a powerful, feature-rich Discord bot designed to enhance your server experience with comprehensive moderation tools, engaging economy systems, utility features, and much more.

Instead of installing separate bots for music, moderation, economy, and fun, TitanBot combines all these domains in a single installation. Features span moderation (bulk ban/kick, user notes, case management), economy (shop, inventory, gambling, money transfers), entertainment (wanted posters, random facts, text reversal), advanced ticketing (claim, priority, transcripts), and server statistics (member counters, voice counters).

Additional features include reaction roles, leveling systems with auto-assigned role rewards, giveaways with multiple winners, birthday tracking with timezone support, utility tools like report systems and todo lists, welcome messages with auto-roles, and music playback with 24/7 mode and support for Spotify, Deezer, YouTube, and Apple Music.

Architecture: Discord.js v14 with PostgreSQL

TitanBot is written in JavaScript using Discord.js v14, the modern Discord API library. It requires Node.js 20.10.0 or higher. Data persistence relies on PostgreSQL; a memory storage fallback exists but is not production-recommended.

The package.json lists dependencies including discord.js, Express (for the health endpoint), node-cron (for scheduled tasks), pg (PostgreSQL client), winston (logging), zod (schema validation), and riffy (music library for Lavalink v4). The bot also includes automatic database migration with schema versioning.

Music playback uses Lavalink v4 via the Riffy library. By default, TitanBot loads public Lavalink nodes from `lavalink/nodes.json`. You can self-host Lavalink with Docker Compose using the local-lavalink profile or point to a custom Lavalink instance via environment variables.

Docker deployment and quick setup

Docker Compose simplifies setup. Clone the repository, configure environment variables, and run:

git clone https://github.com/codebymitch/TitanBot.git
cd TitanBot
cp .env.example .env

Edit `.env` with your Discord bot credentials:

DISCORD_TOKEN=your_discord_bot_token_here
CLIENT_ID=your_discord_client_id_here
GUILD_ID=your_discord_guild_id_here

Then start the containers:

docker compose up -d --build

This launches the bot and PostgreSQL together. Check status with `docker compose ps` and `curl http://localhost:3000/health`. The compose file sets `AUTO_MIGRATE=true` for automatic schema application, and `POSTGRES_SSL=false` for the bundled database.

Manual installation requires Node.js 20.10.0 and separate PostgreSQL setup. After cloning and installing dependencies, configure `.env` and run `npm start`.

Database schema and configuration

TitanBot manages PostgreSQL schema via migration scripts. The `.env` file controls connection settings: `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`. The `.env.example` provided in the repository documents all available variables. Production deployments should use a connection URL in `POSTGRES_URL` with SSL enabled if the database is remote. Railway deployments should use the private `POSTGRES_URL` or `DATABASE_URL` variable which includes SSL.

PostgreSQL pool settings are configurable: `POSTGRES_MAX_CONNECTIONS` (default 20), `POSTGRES_MIN_CONNECTIONS` (default 2), `POSTGRES_CONNECTION_TIMEOUT` (default 10000 ms), `POSTGRES_IDLE_TIMEOUT` (default 30000 ms), `POSTGRES_RETRIES` (default 3), `POSTGRES_BACKOFF_BASE` (100 ms), and `POSTGRES_BACKOFF_MULTIPLIER` (2). The migration table is defined by `POSTGRES_MIGRATION_TABLE` (default `schema_migrations`), and schema versioning uses `SCHEMA_VERSION` and `SCHEMA_VERSION_LABEL` (default `baseline-v1`). Available npm scripts for migration include `npm run migrate` (apply migrations), `npm run migrate:check` (check status), `npm run migrate:status` (show status), and migration key utilities.

Logging behavior is controlled by `LOG_LEVEL` (options: error, warn, info, http, verbose, debug, silly) and `LOG_TO_FILE`. In production, `LOG_LEVEL=warn` shows only critical issues and startup status; `LOG_LEVEL=info` provides operational detail. The bot uses Winston for logging and supports daily log rotation via `winston-daily-rotate-file` when logging to files. Backup and restoration are handled by `npm run backup:db` and `npm run restore:db` scripts, which use environment variable `BACKUP_DIR` (default `./backups`) and `BACKUP_RETENTION_DAYS` (default 14). A drill backup script is available via `npm run backup:drill`.

Music, giveaways, and moderation

Music commands use `/play <song>` from a voice channel or `/join` to connect silently. Prefix shortcuts include `np` (now playing), `pause`, `resume`, `skip`, `stop`, `volume <0-100>`, and `music` subcommands. Lavalink connection defaults to public v4 nodes but can be overridden with `LAVALINK_NODES_FILE` or `LAVALINK_NODES` environment variables.

Giveaways support multiple winners and automatic winner selection with a reroll system. The README states they include auto picking and reroll capability. Moderation tools include mass ban/kick capabilities, user notes for detailed records, and case management to view all moderator actions.

The ticket system provides claim and priority options for staff, ticket limits to prevent spam, and a transcript system to save ticket history. The leveling system tracks XP automatically based on messages, assigns roles based on level thresholds, and supports custom configuration.

Configuration, health checks, and port fallback

TitanBot's health endpoint responds at `http://localhost:3000/health` and is built into the Docker Compose setup with 30-second interval checks, 5-second timeouts, and retry limits of 3.

The bot automatically handles port conflicts. If `PORT` (default 3000) is occupied, TitanBot tries subsequent ports up to the limit set by `PORT_RETRY_ATTEMPTS` (default 5). This is configurable via the `.env` file along with other API settings: `WEB_HOST` (default `0.0.0.0`) and `CORS_ORIGIN` (default `*` for development).

Environment variable `OWNER_IDS` (optional) restricts administrative commands to specified users. Sentry error tracking is optional via `SENTRY_DSN`. The `NODE_ENV` variable controls whether the bot runs in `production`, `development`, or `test` mode; any non-`production` value is treated as development. `AUTO_MIGRATE=true` (set in Docker Compose) automatically applies database schema changes on startup.

Maintenance status and deployment options

The last push to TitanBot was on 2026-09-03. Recent releases include v3.0.0 (2026-07-13), v2.0.0 (2026-06-16), and v1.1.1 (2026-05-02). The project shows active maintenance with regular updates. The project follows semantic versioning; version 2.1.0 is documented in the repository's package.json.

Docker images are automatically published to GitHub Container Registry on every push to main:

docker pull ghcr.io/codebymitch/titanbot:main

For Kubernetes deployment, the bot supports configuration via environment variables. Node.js version 20.10.0 or higher is required; this constraint is specified in the package.json `engines` field.

The health endpoint is configurable and responds to HTTP requests. Docker Compose includes a health check that runs every 30 seconds with a 5-second timeout and 3 retry attempts, with a 40-second start period before health checks begin. If the configured `PORT` (default 3000) is already in use, TitanBot automatically tries the next available port up to the limit set by `PORT_RETRY_ATTEMPTS` (default 5).

Editorial conclusion

Use TitanBot if you need a feature-complete Discord bot with minimal configuration and Docker support. Do not use it if you need advanced customization or if you prefer lighter bots with fewer features. Before deploying, set the required environment variables (DISCORD_TOKEN, CLIENT_ID, GUILD_ID) and decide on PostgreSQL or fallback storage.

Frequently asked questions

Official sources

1. codebymitch/TitanBot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases