Skip to content

Setup

Here are some instructions to get esmBot up and running from source.

Recommended system requirements
  • 64-bit CPU/operating system
  • Quad-core CPU or better
  • 512MB or more of RAM
  • Unix-like (e.g. Linux, macOS, FreeBSD) operating system or virtual machine (Ubuntu or Fedora are recommended)

Warning

If you want to run the bot on Windows, Windows Subsystem for Linux is recommended. This guide is somewhat centered around Unix-like systems, so for now you're mostly on your own if you decide not to use WSL.

If you have any further questions regarding setup, feel free to ask in the #support channel on the esmBot Support server.

Tip

You can run the bot using Docker or Podman for a somewhat simpler setup experience. Click here to go to the container setup guide.

1. Install the required native dependencies.

Choose the OS you're using below for insallation instructions.

These instructions apply to Debian version 12 (bookworm) or Ubuntu version 24.04 (noble) or later. 

sudo apt-get install git curl build-essential cmake ffmpeg sqlite3 ttf-mscorefonts-installer libmagick++-dev libvips-dev libzxing-dev
On older Debian/Ubuntu versions, you may need to install some of these packages (notably libcgif-dev and meson) through alternative methods.

These instructions apply to Fedora 38/RHEL 9 or later.

Some of these packages require that you add the RPM Fusion and/or EPEL repositories. You can find instructions on how to add them here. 

sudo dnf install git curl cmake ffmpeg sqlite gcc-c++ ImageMagick-c++-devel vips-devel cabextract zxing-cpp-devel
On RHEL-based distros like AlmaLinux and Rocky Linux, you may need to add Remi's RPM Repository for the vips package.

Some fonts used in the bot (e.g. Impact) require installing the MS Core Fonts package, which is unavailable through most RHEL repositories. You can install it using the following command (you're on your own regarding dependencies, each RHEL derivative handles them differently): 

sudo rpm -i https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm

These instructions should apply to version 3.17 or later. 

sudo apk add git curl msttcorefonts-installer python3 sqlite3 alpine-sdk cmake ffmpeg imagemagick-dev vips-dev zxing-cpp-dev


sudo pacman -S git curl cmake ffmpeg npm imagemagick libvips sqlite3 zxing-cpp
You'll also need to install ttf-ms-win10-auto from the AUR.

brew install cmake ffmpeg imagemagick libvips
The zxing-cpp package is not available through Homebrew, so unfortunately the QR commands will be unavailable on macOS without further intervention.

2. Install Node.js.

Node.js is the runtime that esmBot is built on top of. The bot requires version 20.12.0 or above to run.

We suggest using nvm to manage your Node.js install. Run the following command to install it: 

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Then run the following to install Node.js: 

nvm install 20
nvm use 20

esmBot uses the pnpm package manager to manage dependencies and run build scripts. You can use Corepack (a tool included with Node.js) to install it: 

corepack enable
corepack prepare pnpm@latest --activate

3. Set up the database.

esmBot officially supports two database systems: SQLite and PostgreSQL. While SQLite is smaller and requires no initial setup, PostgreSQL has better performance (especially in large environments).

Tip

If you're new to databases and self-hosting, choose SQLite.

If you would like to use the SQLite database, no configuration is needed and you can move on to the next step.

If you would like to use the PostgreSQL database, view the setup instructions here and come back here when you're finished.

4. Clone the repo and install the required Node modules.

cd ~
git clone --recursive https://github.com/esmBot/esmBot
cd esmBot
pnpm install
pnpm build

Note

On macOS, you'll need to replace the last command in the above list with the following: 

pnpm build --CDWITH_ZXING=OFF

Lavalink is the audio server used by esmBot for music playback. If you do not plan on using this feature, you can safely skip this step.

Warning

There are websites out there providing lists of public Lavalink instances that can be used with the bot. However, these are not recommended due to performance/security concerns and missing features, and it is highly recommended to set one up yourself instead using the steps below.

esmBot requires Lavalink version v4 or later, which requires a Java (17 or later) installation. You can use SDKMAN to install Eclipse Temurin, a popular Java distribution: 

sdk install java 17.0.11-tem

Initial setup is like this: 

cd ~
mkdir Lavalink
cd Lavalink
curl -OL https://github.com/lavalink-devs/Lavalink/releases/latest/download/Lavalink.jar
ln -s ~/esmBot/application.yml .
To run Lavalink, you can use this command: 
java -jar Lavalink.jar

Info

You'll need to run Lavalink alongside the bot in order to use it. There are a few methods to do this, such as the screen command, creating a new systemd service, or simply just opening a new terminal session alongside your current one.

6. Configure the bot.

Configuration is done via environment variables which can be specified through a .env file. Copy .env.example to get a starter config file: 

cp .env.example .env

Tip

If you can't see either of these files, don't worry - Linux treats files whose names start with a . as hidden files.

To edit this file in the terminal, run this command: 

nano .env
This will launch a text editor with the file ready to go. Create a Discord application here and select the Bot tab on the left, then create a bot user. Once you've done this, copy the token it gives you and put it in the TOKEN variable.

When you're finished editing the file, press Ctrl + X, then Y and Enter.

An overview of each of the variables in the .env file can be found here.

7. Run the bot.

Once everything else is set up, you can start the bot like so: 

pnpm start
If the bot starts successfully, you're done! You can invite the bot to your server by generating an invite link under OAuth -> URL Generator in the Discord application dashboard.

Note

You will need to select the bot and applications.commands scopes. The following permissions are needed in most cases for the bot to work properly:

Required permissions
click to enlarge

If you want the bot to run 24/7, you can use the PM2 process manager. Install it using the following command: 

pnpm add -g pm2

Once you've done that, you can start the bot using the following command: 

pm2 start ecosystem.config.cjs

Tip

If you wish to update the bot to the latest version/commit at any time, run the following commands: 

git pull
pnpm install
pnpm build

Troubleshooting

Error: Cannot find module './build/Release/image.node'

The native image functions haven't been built. Run pnpm build to build them.

pnpm install or pnpm build fails with error 'ELIFECYCLE  Command failed.'

You might need to install node-gyp. You can do this by running the following: 

pnpm i -g node-gyp
rm -rf node_modules
pnpm install

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL isn't running, you should be able to start it on most Linux systems with sudo systemctl start postgresql. If you don't intend to use PostgreSQL, you should take another look at your DB variable in the .env file.

Gifs from Tenor result in a "no decode delegate for this image format" or "improper image header" error

Tenor GIFs are actually stored as MP4s, which libvips can't decode most of the time. You'll need to get a Tenor API key from here and put it in the TENOR variable in .env.

If you have any further questions regarding self-hosting, feel free to ask in the #support channel on the esmBot Support server.