To set up the bot and its services, we first need to prepare our server. The steps may vary slightly depending on your server's operating system. Choose the instructions that match your OS. This guide assumes you have basic command line and server-managing skills.
MacOS/Linux Instructions
For Debian based Linux distributions using the x86-64 architecture
Next, let's install the pm2 process manager. This is how we'll run the Discord bot in a production environment (instructions from ).
# Install pm2 using npm
npm install pm2@latest -g
# or install pm2 using yarn:
yarn global add pm2
# Verify pm2 version:
pm2 -v
Finally, let's install Docker and Docker Compose. These tools enable us to efficiently manage our PostgreSQL and caching databases with added flexibility, reducing complex configurations and simplifying overall management. Instructions are taken from here: (if you're using Ubuntu, you can go straight to here: ) and here: .
# Uninstall conflicting packages:
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done
# Clean up unused packages:
sudo apt autoremove
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources (if you get errors on this step, check the official Docker documentation):
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
# Install the latest version of Docker and its tools:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Start Docker (if it's not already running):
sudo systemctl start docker
# Configure Docker to start on boot:
sudo systemctl enable docker.service
sudo systemctl enable containerd.service
# Make it so we don't have to use sudo to use Docker:
sudo groupadd docker
sudo usermod -aG docker $USER
# Either log out and log back into your user account or run this command:
newgrp docker
# If you get this error:
# WARNING: Error loading config file: /home/user/.docker/config.json -
# stat /home/user/.docker/config.json: permission denied
# Run these commands:
sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R
# Verify Docker version:
docker version
# Verify Docker Compose Version:
docker compose version
# Run an example Docker container to ensure it's working (this should print a whole bunch of information):
docker run hello-world
With all necessary tools installed and configured, we're ready to run the bot and its services.
Windows Instructions
First, let's install Node.js and the Yarn package manager on our machine. Open PowerShell and type in the following commands (instructions taken from ):
# Download and install fnm (you might have to restart your terminal to use fnm):
winget install Schniz.fnm
# Download and install Node.js:
fnm install 22
# Verify the Node.js version:
node -v # Should print "v22.14.0".
# Download and install Yarn:
corepack enable yarn
# Verify Yarn version:
yarn -v
Next, let's install git. This will enable us to clone the GitHub repository to our local machine.
Open a web browser and head to . You should see a page like this:
Underneath the "Standalone Installer" section, click on the link that says "64-bit Git for Windows Setup."
This should download the git installer to your machine. Once it's finished downloading, open the installer and follow the steps to install git. After git is finished installing, open PowerShell again and type in the following to verify that git was installed correctly:
# Verify git version (you might have to relaunch your terminal if you're using and already open window):
git --version
Now, let's install the pm2 process manager. This is how we'll run the Discord bot in a production environment (instructions from ). Run the following in PowerShell:
# Install pm2 using npm:
npm install pm2@latest -g
# or install pm2 using yarn:
yarn global add pm2
# Verify pm2 version:
pm2 -v
Finally, let's install Docker and Docker compose. These tools will make it so that we can run our PostgreSQL and caching databases without needing a separate Linux server to run them. All instructions are taken from here and here .
First, open a PowerShell window as an Administrator and type in the following to install the WSL runtime:
# Install the WSL runtime:
wsl --install
After the installation is complete, restart your computer.
Next, open a web browser and go to . You should see a page like this:
Click on the button that says, "Docker Desktop for Windows - x86_64".
This should download the Docker installer to your machine. Once it's finished downloading, open the installer and follow the instructions to install Docker onto your machine. If it prompts you to use either Hyper-V or WSL for containers, choose WSL. Once the installation is finished, restart your computer.
Finally, open your search bar and search for Docker. Click on the option that says, "Docker Desktop". Wait for Docker to start. Once it starts up, open a new PowerShell window and type in the following:
# Verify Docker version:
docker --version
# Verify Docker Compose version:
docker compose version
# Run an example Docker container to ensure it's working (this should print a whole bunch of information):
docker run hello-world
With all necessary tools installed and configured, we're ready to run the bot and its services.
Step 3: Setup and configure the bot
Once our server is prepared, we can proceed to download and configure the bot by following these steps:
1
Clone the bot's repository to your server
Open a terminal window and paste in the following:
# Clone the GitHub repository to our local machine:
git clone -b main --single-branch --depth 1 https://github.com/ahmadk953/poixpixel-discord-bot.git
# Change-Directory into the bot's directory:
cd poixpixel-discord-bot
Now, we can start configuring the bot
2
Configure the bot
Run the following to copy the config.example.json file to a new file named config.json. This is where we'll store all our bot configuration options, including the bot's token.
# Copy and rename config.example.json to config.json:
cp config.example.json config.json
Next, open the new config.json file in a text editor like vim or nano on Mac/Linux, or Visual Studio Code on Windows. When you open the file, it should look something like this:
We'll fill in the details for the caching and PostgreSQL databases later. Lastly, let's get the bot ready for when we eventually start it up.
3
Setup and compile the source code
Open a terminal window in the projects root directory and run the following commands to install dependencies and compile the source code.
# Install dependencies (if asked to continue, press 'y' and hit enter for yes):
yarn install --immutable
# Invoke build tools:
yarn prepare
# Compile source code:
yarn compile
Now that we've finished preparing the bot, let's move onto setting up its resources
Step 4: Set up the PostgreSQL and caching databases
Now, it's time to set up the bot's services. Follow the steps below to set up the PostgreSQL and caching databases.
1
Generate SSL certificates
Note that this step might be a little tricky on Windows and that it's not fully tested. If anyone would like to fully test and contribute their finding, that would be extremely helpful.
If on Windows, type the following into your terminal. If you're on Linux/MacOS, you can skip this step.
# Launch WSL:
wsl
# Head into the directory where the bot's files are located:
cd /mnt/DRIVELETTER/PATH/TO/DISCORD/BOT/DIRECTORY
Make sure to replace DRIVELETTER/ATH/TO/DISCORD/BOT/DIRECTORY with the path to your bot's directory as you normally would. For example:
cd /mnt/c/Users/ahmad/Downloads/poixpixel-discord-bot
There's already a shell script in the project's directory that'll generate the SSL certificates for you. Just run the following commands to execute the script:
Note that it's always a good idea to check scripts that you are about to execute from any source online for malicious code. If you don't understand what the script is doing or, don't know how to read bash scripts, you can always ask an AI tool to explain it for you. The source code for the script that we are about to execute can be found .
# Make the script executable:
chmod +x generate-certs.sh
# Run the script:
./generate-certs.sh
Note that these SSL certificates will expire after a year. Simply re-run the script to generate new ones and restart both the bot and the Docker containers.
Now that we have the SSL certificates set up, we can move onto configuring environment variables for our Docker containers. Windows users can now switch back to their normal terminals by simply closing and re-opening their terminals.
2
Set up environment variables
Run the following to copy the .env.example file to a new file named .env. This is where our database username and password, as well as our caching database's password will live.
# Copy and rename .env.example to .env:
cp .env.example .env
Next, open the new .env file. You should see something like this:
With our bot's resources configured, let's launch their Docker containers.
3
Spin up the Docker containers
This step is relatively simple; all you have to do is run the command below to start up the Docker containers
# Spin up the Docker containers:
docker compose up -d
And in case you need to stop the containers:
# Stop the containers WITHOUT deleting and removing them:
docker compose stop
# Stop the containers and DELETE/REMOVE THEM. Note your DATA WILL BE SAFE. This just deletes the actual Docker containers:
docker compose down
Lastly, to restart the containers and view their logs, you can run the following commands:
Once all the bot's resources are operational, let's complete the configuration and start it up.
Step 5: Finish bot configuration
Now that we have the bot's resources up and running, let's finish configuring it. Open the config.json file again and scroll to the section that look like this:
You can use the following template to obtain the PostgreSQL connection string: postgresql://username:password@localhost/database.
Since the bot and the Postgres instance run on the same server, the format should be: postgresql://username:password@localhost/database.
Fill out the format as follows:
Replace username with the value from the POSTGRES_USER environment variable.
Replace password with the value from the POSTGRES_PASSWORD environment variable.
Replace database with the value from the POSTGRES_DB environment variable.
Once updated, it should look like this example: postgresql://bot-user:password@localhost/bot-db. Replace POSTGRESQL_CONNECTION_STRING with this value.
Lastly, replace MAX_RETRY_ATTEMPTS with the desired maximum number of connection attempts. Then, change RETRY_DELAY_IN_MS to specify the wait time in milliseconds between retries. You should now have something that look like this:
You can use the following template to obtain the Redis (in our case, Valkey since they're compatible with each other) connection string: redis://username:password@host:port.
In our case, this is the format we'll be using: redis://default:password@localhost:6379. All you have to do is replace password with the value you set for the VALKEY_PASSWORD environment variable. Replace REDIS_CONNECTION_STRING with this value.
Lastly, replace RETRY_ATTEMPTS with the desired maximum number of connection attempts. Then, change INITIAL_RETRY_DELAY_IN_MS to specify the wait time in milliseconds between retries. You should now have something that look like this:
# Start the bot in production mode:
yarn start:prod
To view the bot's logs, type in this command:
# To view bot logs:
pm2 logs
To stop the bot, run this command:
# To stop the bot:
pm2 stop poixpixel-discord-bot
Finally, go to your Discord server and test out the bot's commands to make sure that it's working. Once you have verified that it is working, you can move onto reading about some of the bot's basic configuration options linked below.
