Local Setup & Installation

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• package.json
• config.example.json
• src/db/db.ts
• src/discord-bot.ts

This guide provides a comprehensive overview of the steps required to set up the Poixpixel Discord Bot in a local development environment. The process involves configuring prerequisites, managing dependencies, setting up essential services like PostgreSQL and Redis, and initializing the application through the provided CLI scripts.

The bot is built using TypeScript and Node.js, utilizing Drizzle ORM for database interactions and Winston for structured logging. It is designed to run in multiple environments, including local development, PM2, and Docker.

Sources: CONTRIBUTING.md:46-51, src/discord-bot.ts:1-5, SECURITY.md:16

Prerequisites

Before beginning the installation, the following software must be installed on your local machine:

Requirement	Version / Detail
Node.js	>= 22.0.0
Yarn	4.10.3+ (managed via Corepack)
PostgreSQL	Primary relational database
Redis	Used for caching and fault tolerance
Git	For version control

Sources: CONTRIBUTING.md:44-51, package.json:96-98

Initial Installation Steps

The setup begins by cloning the repository and preparing the package manager.

1. Clone the Repository:

   git clone https://github.com/ahmadk953/poixpixel-discord-bot.git
   cd poixpixel-discord-bot
   

2. Enable Corepack: This ensures the correct version of Yarn is used as defined in the project.

   corepack enable
   

3. Install Dependencies:

   yarn install
   

The following diagram illustrates the high-level initialization flow when the bot starts up.

Configuration

The bot requires a config.json file populated with Discord API credentials and service connection strings. An example file, config.example.json, is provided as a template.

Essential Configuration Fields

Field	Description
token	Discord bot token from the Developer Portal
clientId	The Application ID of the bot
guildId	The primary Discord server ID for command deployment
database.poolingDbConnectionString	PostgreSQL connection string (typically for PgBouncer)
database.directDbConnectionString	Direct PostgreSQL connection string for migrations
redis.redisConnectionString	Connection string for the Redis instance

Sources: config.example.json:10-45, CONTRIBUTING.md:71-76

Database Initialization

The project uses Drizzle ORM. After configuring the connection strings, you must run migrations to set up the schema:

npx drizzle-kit migrate

If your PostgreSQL setup requires TLS, you can generate the necessary certificates using the provided script:

bash generate-certs.sh

Sources: CONTRIBUTING.md:78-85, src/db/db.ts:27-30

Development Workflow Commands

Once configured, various yarn scripts are available to manage the bot's lifecycle.

Command	Action
yarn dev	Compiles TypeScript and starts the bot with command deployment
yarn no-deploy	Starts the bot without re-registering Slash commands (faster iteration)
yarn compile	Runs the TypeScript compiler (tsc)
yarn lint	Executes ESLint and checks types without emitting code
yarn format:fix	Automatically fixes code formatting using Prettier
yarn undeploy-commands	Removes all registered guild commands from the Discord API

Sources: package.json:11-20, README.md:27-41

Execution Logic

The bot uses a specific sequence to establish a stable database connection, attempting multiple connection types (pooled vs. direct) before failing.

Production Deployment (Optional)

For local testing in a production-like state, the project supports PM2 and Docker.

1. PM2 Setup:

   yarn start    # Starts the bot with PM2
   yarn restart  # Restarts the PM2 process
   

2. PgBouncer (Docker): A specialized PgBouncer configuration is available in ./docker/pgbouncer to handle connection pooling efficiently. It uses an entrypoint.sh script to dynamically generate pgbouncer.ini based on environment variables.

Sources: package.json:14-15, docker/pgbouncer/README.md:1-15, docker/pgbouncer/entrypoint.sh:5-15

Summary

Setting up the Poixpixel Discord Bot requires a modern Node.js environment and active instances of PostgreSQL and Redis. By following the standard installation flow—dependency installation, configuration via config.json, and database migration—developers can establish a functional local instance. The project provides utility scripts for linting, formatting, and rapid command-less restarts to streamline the development experience.

Sources: CONTRIBUTING.md:200-210, README.md:10-15