Production Deployment Process
Relevant source files
The following files were used as context for generating this wiki page:
This page outlines the technical procedures and architectural requirements for deploying the Poixpixel Discord Bot into a production environment. While the project is currently in a testing state, the infrastructure is built to support robust execution using PM2 for process management, PostgreSQL for persistent storage, and Redis for caching.
The deployment process involves environment preparation, dependency resolution via Yarn (Corepack), TypeScript compilation, database migrations using Drizzle Kit, and command registration with the Discord API.
Sources: README.md:3-5, CONTRIBUTING.md:41-45
Infrastructure & Prerequisites
Production deployment requires a specific set of runtime environments and external services to ensure the bot functions correctly.
Core Requirements
- Node.js Runtime: Version >= 22.0.0 is mandatory.
- Package Management: Yarn 4.10.3+ managed via Corepack.
- Databases:
- PostgreSQL: Primary database for leveling, moderation, and user data.
- Redis: High-speed caching for counting systems and session data.
- Process Management: PM2 is the designated tool for maintaining bot uptime and handling restarts.
Sources: package.json:101-103, CONTRIBUTING.md:41-50, config.example.json:23-45
Configuration Architecture
The bot utilizes a config.json file derived from config.example.json. This file contains sensitive credentials that must be managed securely and never committed to version control.
| Category | Key Configurations | Purpose |
|---|---|---|
| Authentication | token, clientId | Discord API credentials. |
| Database | poolingDbConnectionString | PostgreSQL connection for general queries. |
| Database | directDbConnectionString | Connection used for migrations (bypasses pooling). |
| Redis | redisConnectionString | Redis server address. |
| Guild | guildId | Targeted server for command deployment. |
Sources: config.example.json:11-45, SECURITY.md:89-91
Deployment Workflow
The following diagram illustrates the sequence of operations required to move code from the repository to a running production instance.
The workflow ensures that the environment is consistent and that the database schema matches the application code before execution begins.
Sources: CONTRIBUTING.md:52-87, package.json:12-24
Step 1: Dependency and Environment Setup
The project uses ts-patch and husky as post-install hooks to ensure the build environment is prepared.
corepack enable
yarn install
Sources: package.json:25, CONTRIBUTING.md:60-63
Step 2: Database Migration
Migrations are handled via Drizzle Kit. The directDbConnectionString should be used here to ensure schema changes are applied without proxy interference.
npx drizzle-kit migrate
Sources: CONTRIBUTING.md:78-80, config.example.json:30-32
Step 3: Compilation and Process Execution
The bot is written in TypeScript and must be compiled to JavaScript in the ./target directory before it can be run. The yarn start script automates compilation followed by a PM2 launch.
Command Deployment Architecture
Unlike global commands which can take an hour to propagate, this bot uses guild-specific deployment for production efficiency. Commands are auto-discovered from the src/commands/ directory.
Recursive Command Discovery
The deployment utility scans subdirectories (e.g., fun, moderation, util) to find .js files in the build target. Each command must export a data (SlashCommandBuilder) and an execute function.
// Location: src/util/deployCommand.ts
export const getFilesRecursively = (directory: string): string[] => {
// Logic to walk target/commands and return valid .js paths
};
Sources: src/util/deployCommand.ts:18-38, CONTRIBUTING.md:214-222
Command Update Process
The deployment script performs a PUT request to the Discord API using the applicationGuildCommands route. This replaces the entire command list for the configured guild with the current local definitions.
| Operation | Command | Description |
|---|---|---|
| Full Deploy | yarn start | Compiles and registers all commands before starting. |
| Skip Deploy | yarn no-deploy | Starts the bot using existing registered commands. |
| Cleanup | yarn undeploy-commands | Removes all registered commands from the guild. |
Sources: package.json:15-18, src/util/deployCommand.ts:51-87
Operational Management
Once deployed, the bot is managed as a background service. PM2 provides the necessary tooling for lifecycle management.
Monitoring and Restarts
- Startup:
yarn start(Usespm2 start ./target/discord-bot.js --name poixpixel-discord-bot) - Restarting:
yarn restart(Invokespm2 restart) - Logging: Logs should be monitored via PM2 logs or the configured OTLP telemetry endpoint if
telemetry.otel.enabledis set totrueinconfig.json.
Sources: package.json:16-17, config.example.json:117-125
Security in Production
- Secret Management: Secrets must be stored outside of the version control system.
- TLS/SSL: If using PostgreSQL or Redis in a remote production environment, connection strings should use
rediss://or appropriate TLS parameters. - Hardening: Minimize the bot's Discord permissions to the specific intents requested in the
discord-bot.tsentry point (e.g.,Guilds,GuildMembers,MessageContent).
Sources: SECURITY.md:89-98, config.example.json:42-43, src/discord-bot.ts:74-82
Summary
The production deployment process for the Poixpixel Discord Bot emphasizes a structured transition from TypeScript source to a PM2-managed JavaScript execution. By utilizing Drizzle for migrations, Redis for caching, and automated guild-specific command registration, the bot maintains high availability and rapid update cycles. Developers must ensure that the node engine (>=22) and database connections are correctly configured in config.json before initiating the yarn start sequence.