Getting Started

Thanks for choosing SudoBot! In this article you'll learn how to set up a custom instance of SudoBot and configure it so that it does exactly what you want.

Requirements

These are the requirements to host SudoBot:

• A Discord API Application token (Go to Discord Developer Portal to obtain a token)
• Node.js version 18 or higher
• A PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out Neon)

Additionally, you can also set these up if you want to use them:

• Cat and dog API Token (for fetching cat and dog images using cat and dog commands, the tokens can be obtained at thecatapi.com and thedogapi.com)
• Pixabay API Token to use the pixabay command (can be obtained here)
• A Discord Webhook URL for sending error reports

Cloning the project and setting up

First of all, clone the repository or download the latest release and extract it.

To clone the git repository, run this command:

git clone https://github.com/onesoft-sudo/sudobot

You can also checkout the subversion repository:

svn checkout https://svn.onesoftnet.eu.org/svn/sudobot sudobot

After this command finishes, go inside of the directory. (sudobot/ if you cloned it using the above command)

To make sure you recieve the latest updates as main isn't getting updated as often, run the following commands after you go inside of the sudobot directory.

git switch 8.x && git pull origin 8.x

That command will switch you to 8.x and pull the latest updates from there.

Once that is done, install the dependencies using the following command:

npm install -D

Or, if you prefer using bun over NPM, you run the following command to install the dependencies:

bun install -D

Building the bot

Now we need to invoke the TypeScript compiler (tsc) to build the bot and generate compiled JavaScript files that the Node.js interpreter can run. To compile the bot, simply run:

npm run build

Or if you're using bun, you can run the following command to build the bot:

bun run build

If you don't have enough resources, this command will fail with heap allocation errors. If that happens, or if you don't want to build it yourself, don't worry. You can download prebuilt versions for every release. The builds are tested on Node.js v21, however they should also work with v20. You might see that only Linux and macOS (darwin) releases are available. This doesn't mean you cannot run the bot on Windows systems - only the native bindings are platform dependent. You don't need to worry about that in most cases and the bot will just work fine. You can download the prebuilt versions in the GitHub releases page: https://github.com/onesoft-sudo/sudobot/releases/latest

As always if you ever encounter errors with commands or you see something is not working as you expect, you can join our Discord Server and ask for help!

JSON Configuration Schema

Generate the JSON config schema files using the following command:

npm run gen:schema

You can skip this step and move onto the enviroment variables section if you don't mind not having autocompletion in your IDE/editor.

The environment variables

Create a file named .env inside of the root project directory. This file will contain some secret information that the bot needs, to work. (e.g. bot token)

Then you need to add a few variables to .env file:

# This is your bot's token.
TOKEN=

# This is the home server, where the bot will search for emojis.
HOME_GUILD_ID=

# The client ID of your bot application.
CLIENT_ID=

# Database URL
DB_URL=

Here:

• TOKEN is your bot token. Make sure to put the correct token here, otherwise the bot won't be able to log in to Discord. The bot token can be obtained from https://discord.com/developers/applications.
• HOME_GUILD_ID is the main server ID of the bot. The bot expects that it will always stay in that server, and it will search for the emojis there. You can download the emojis and use them freely. To download, go to the downloads list.
• CLIENT_ID is the client ID of your bot application. You can obtain the client ID for your bot at https://discord.com/developers/applications.
• DB_URL is the database URL. We'll be talking about this just in a moment. You can jump into that section right now if you want.

A few more environment variables can be specified:

• DEBUG: Used by the Prisma ORM. This enables extra debug logging, aka Verbose Mode.
• SUDO_ENV and NODE_ENV: If one of these is set to dev, then the bot will enter Verbose Mode, and log everything that it does or happens. This is useful if you want to debug the bot or troubleshoot something.
• CAT_API_TOKEN: The Cat API token to use when fetching cat images, using cat command.
• DOG_API_TOKEN: The Dog API token to use when fetching dog images, using dog command.

Setting up a Database for the bot

As we've said before, DB_URL is the environment variable that you need to put in .env and the value of this variable should be the database URL. SudoBot at the moment, only supports PostgreSQL.

Your database URL should look like this if you're using PostgreSQL:

postgresql://username:password@hostname:port/dbname

• username is your database username (usually this is postgres)
• password is your database password
• hostname is your database hostname
• port is your database port (usually this is 5432)
• dbname is your database name (usually this is postgres)

After you have set the database URL inside .env, you can run the following command:

npx prisma db push

This will create the necessary tables for you inside the database.

Configuration

Now it's time to configure the bot. Now, SudoBot comes with the config files bundled already, but you should edit them.

Step 1. Open up config/config.json and you have two options:

Remove everything inside of the file, and just put an empty object {} inside of that file and save it if you don't want to configure anything and just want the default settings. Or,

Manually set the settings inside of the file. If you're following along this documentation and have run the script generate-config-schema.js (previously specified here), then when you edit the file, you can remove everything inside of the file, and put the following JSON object inside of that file:

{
    "$schema": "./schema/config.json",
    "guild_id": {}
}

Replace guild_id with your main guild ID, where you want to use the bot. If you want to use the bot in multiple servers, specify them here, as the keys of the root object.

If you're using an IDE or editor like VS Code or WebStorm, you can hit Ctrl + Space (or Cmd + Space if you're on a Mac) to get auto completion and see available options. The IDE/editor will highlight errors inside of your config file if you have any.

Step 2. Open up config/system.json file and similarly here you'll get autocompletion. But you don't need to delete everything here, just change the system_admins property, which is an array of user IDs. Just add your User ID into the array. System Admins are those who have full access to the bot and can control everything. They are able to run commands like -eval.

Registering Application Commands

If you want to use the application slash commands and context menu commands of SudoBot, you have to register it to the API first. To do that, simply run:

node scripts/deploy-commands.js

Pass the --guild option to register guild commands instead of global commands, and --clear to clear all the registered slash commands in the API.

Starting the bot

Now it's time to start the bot. Run the following command to start the bot:

npm start

Or in a production enviroment, it's best to use the following command as it uses the PM2 process manager.

npm run start:prod

Or if you want to see the process output in real time while in a production enviroment you can run the following:

npm run start:prod -- --no-daemon

Or if you are using Bun, you can start the bot up without compilation. To start in dev mode, run the following command:

bun dev

Or if you need to run it in a production enviroment, run the following command:

bun start:prod

Or if you want to see the process output in real time while in a production enviroment you can run the following:

bun start:prod --no-daemon

And if everything was configured correctly, the bot will log in successfully to Discord. Congratulations, you've set up your own instance of SudoBot!

Emojis

The bot uses some custom emojis and it will try to find those emojis in the Home Guild (The main server, which is configured in HOME_GUILD_ID environment variable).

The emojs are freely available for download at the download site. The bot uses some other emojis as well, if you want you can download them from emoji.gg.

If you don't add these emojis, the bot may send messages that look weird or too simple.

Help & Support

In case if you're facing issues, feel free to open an issue at GitHub. Or you can contact the Author of the bot in the following ways:

• Email: rakinar2@onesoftnet.eu.org
• Discord: @rakinar2
• Discord Servers: OSN's server

Give the repository a star to show your support! We'll be really thankful if you do.