%28docs%29/getting-started-v8/page.mdx

---
title: Getting Started Guide for SudoBot v8 - SudoBot
short_name: Getting Started (v8)
---

import Callout from "@/components/Alerts/Callout";

# 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.

<Callout type="info">
    If you don't want to set the bot up yourself and want a pre-hosted solution
    for free, you can contact
    [@rakinar2](https://discord.com/users/774553653394538506) at Discord.
</Callout>

<Callout type="note">
    v9 is the current version of SudoBot. This guide exists for people who want to use
    an older version of SudoBot.
</Callout>

## Requirements

These are the requirements to host SudoBot:

-   A Discord API Application token (Go to [Discord Developer Portal](https://discord.com/developers/applications) to obtain a token)
-   [Node.js](https://nodejs.org) version 18 or higher
-   A PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out [Neon](https://neon.tech))

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](https://thecatapi.com) and [thedogapi.com](https://thedogapi.com))
-   Pixabay API Token to use the `pixabay` command (can be obtained [here](https://pixabay.com/api/docs/))
-   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](https://github.com/onesoft-sudo/sudobot/releases/latest) and extract it.

To clone the [git](https://git-scm.com) repository, run this command:

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

You can also checkout the [subversion](https://subversion.apache.org/) repository:

```bash
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.

```bash
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:

```bash
npm install -D
```

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

```bash
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:

```bash
npm run build
```

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

```bash
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](https://discord.gg/892GWhTzgs) and ask for help!

## JSON Configuration Schema

Generate the JSON config schema files using the following command:

```bash
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:

```bash
# 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](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](https://www.onesoftnet.eu.org/downloads/sudo/emojis/).
-   `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](https://discord.com/developers/applications).
-   `DB_URL` is the database URL. We'll be talking about this just in a moment. You can [jump](getting-started.md#setting-up-a-database-for-the-bot) into that section right now if you want.

A few more environment variables can be specified:

-   `DEBUG`: Used by the [Prisma](https://prisma.io/) 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](getting-started.md#configuration-and-the-environment-variables), `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**.

<Callout type="warning">
    As of November 28, 2023, we no longer officially support MySQL as a database
    for being used with SudoBot. Please migrate to PostgreSQL.
</Callout>

<Callout type="info">
    If you want a free PostgreSQL hosting service, check out
    [Neon](https://neon.tech), [Fly.io](https://fly.io) or [YugabyteDB](https://www.yugabyte.com/). It's easy to set up, and completely free of cost.
</Callout>

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:

```bash
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](getting-started.md#cloning-the-project-and-setting-up)), then when you edit the file, you can remove everything inside of the file, and put the following JSON object inside of that file:

```json
{
    "$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](https://code.visualstudio.com/) or [WebStorm](https://www.jetbrains.com/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:

```bash
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:

```bash
npm start
```

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

```bash
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:

```bash
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:

```bash
bun dev
```

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

```bash
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:

```bash
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](https://www.onesoftnet.eu.org/downloads/sudo/emojis/). The bot uses some other emojis as well, if you want you can download them from [emoji.gg](https://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](https://github.com/onesoft-sudo/sudobot/issues). Or you can contact the Author of the bot in the following ways:

-   Email: [[email protected]](mailto:[email protected])
-   Discord: [@rakinar2](https://discord.com/users/774553653394538506)
-   Discord Servers: [OSN's server](https://discord.gg/JJDy9SHzGv)

Give the repository a star to show your support! We'll be really thankful if you do.
1	rakinar2	575	---
2			title: Getting Started Guide for SudoBot v8 - SudoBot
3			short_name: Getting Started (v8)
4			---
5
6			import Callout from "@/components/Alerts/Callout";
7
8			# Getting Started
9
10			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.
11
12			<Callout type="info">
13			If you don't want to set the bot up yourself and want a pre-hosted solution
14			for free, you can contact
15			[@rakinar2](https://discord.com/users/774553653394538506) at Discord.
16			</Callout>
17
18			<Callout type="note">
19			v9 is the current version of SudoBot. This guide exists for people who want to use
20			an older version of SudoBot.
21			</Callout>
22
23			## Requirements
24
25			These are the requirements to host SudoBot:
26
27			- A Discord API Application token (Go to [Discord Developer Portal](https://discord.com/developers/applications) to obtain a token)
28			- [Node.js](https://nodejs.org) version 18 or higher
29			- A PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out [Neon](https://neon.tech))
30
31			Additionally, you can also set these up if you want to use them:
32
33			- Cat and dog API Token (for fetching cat and dog images using `cat` and `dog` commands, the tokens can be obtained at [thecatapi.com](https://thecatapi.com) and [thedogapi.com](https://thedogapi.com))
34			- Pixabay API Token to use the `pixabay` command (can be obtained [here](https://pixabay.com/api/docs/))
35			- A Discord Webhook URL for sending error reports
36
37			## Cloning the project and setting up
38
39	rakinar2	581	First of all, clone the repository or download the [latest release](https://github.com/onesoft-sudo/sudobot/releases/latest) and extract it.
40	rakinar2	575
41	rakinar2	581	To clone the [git](https://git-scm.com) repository, run this command:
42	rakinar2	575
43			```bash
44			git clone https://github.com/onesoft-sudo/sudobot
45			```
46
47	rakinar2	581	You can also checkout the [subversion](https://subversion.apache.org/) repository:
48	rakinar2	575
49	rakinar2	581	```bash
50			svn checkout https://svn.onesoftnet.eu.org/svn/sudobot sudobot
51			```
52
53			After this command finishes, go inside of the directory. (`sudobot/` if you cloned it using the above command)
54
55	rakinar2	575	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.
56
57			```bash
58			git switch 8.x && git pull origin 8.x
59			```
60
61			That command will switch you to 8.x and pull the latest updates from there.
62
63			Once that is done, install the dependencies using the following command:
64
65			```bash
66			npm install -D
67			```
68
69			Or, if you prefer using bun over NPM, you run the following command to install the dependencies:
70
71			```bash
72			bun install -D
73			```
74
75			## Building the bot
76
77			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:
78
79			```bash
80			npm run build
81			```
82
83			Or if you're using bun, you can run the following command to build the bot:
84
85			```bash
86			bun run build
87			```
88
89			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.
90			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.
91			You can download the prebuilt versions in the GitHub releases page: https://github.com/onesoft-sudo/sudobot/releases/latest
92
93			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](https://discord.gg/892GWhTzgs) and ask for help!
94
95			## JSON Configuration Schema
96
97			Generate the JSON config schema files using the following command:
98
99			```bash
100			npm run gen:schema
101			```
102
103			You can skip this step and move onto the enviroment variables section if you don't mind not having autocompletion in your IDE/editor.
104
105			## The environment variables
106
107			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)
108
109			Then you need to add a few variables to `.env` file:
110
111			```bash
112			# This is your bot's token.
113			TOKEN=
114
115			# This is the home server, where the bot will search for emojis.
116			HOME_GUILD_ID=
117
118			# The client ID of your bot application.
119			CLIENT_ID=
120
121			# Database URL
122			DB_URL=
123			```
124
125			Here:
126
127			- `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](https://discord.com/developers/applications).
128			- `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](https://www.onesoftnet.eu.org/downloads/sudo/emojis/).
129			- `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](https://discord.com/developers/applications).
130			- `DB_URL` is the database URL. We'll be talking about this just in a moment. You can [jump](getting-started.md#setting-up-a-database-for-the-bot) into that section right now if you want.
131
132			A few more environment variables can be specified:
133
134			- `DEBUG`: Used by the [Prisma](https://prisma.io/) ORM. This enables extra debug logging, aka Verbose Mode.
135			- `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.
136			- `CAT_API_TOKEN`: The Cat API token to use when fetching cat images, using `cat` command.
137			- `DOG_API_TOKEN`: The Dog API token to use when fetching dog images, using `dog` command.
138
139			## Setting up a Database for the bot
140
141			As we've said [before](getting-started.md#configuration-and-the-environment-variables), `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.
142
143			<Callout type="warning">
144			As of November 28, 2023, we no longer officially support MySQL as a database
145			for being used with SudoBot. Please migrate to PostgreSQL.
146			</Callout>
147
148			<Callout type="info">
149			If you want a free PostgreSQL hosting service, check out
150			[Neon](https://neon.tech), [Fly.io](https://fly.io) or [YugabyteDB](https://www.yugabyte.com/). It's easy to set up, and completely free of cost.
151			</Callout>
152
153			Your database URL should look like this if you're using PostgreSQL:
154
155			```
156			postgresql://username:password@hostname:port/dbname
157			```
158
159			- `username` is your database username (usually this is `postgres`)
160			- `password` is your database password
161			- `hostname` is your database hostname
162			- `port` is your database port (usually this is `5432`)
163			- `dbname` is your database name (usually this is `postgres`)
164
165			After you have set the database URL inside `.env`, you can run the following command:
166
167			```bash
168			npx prisma db push
169			```
170
171			This will create the necessary tables for you inside the database.
172
173			## Configuration
174
175			Now it's time to configure the bot. Now, SudoBot comes with the config files bundled already, but you should edit them.
176
177			Step 1. Open up `config/config.json` and you have two options:
178
179			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,
180
181			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](getting-started.md#cloning-the-project-and-setting-up)), then when you edit the file, you can remove everything inside of the file, and put the following JSON object inside of that file:
182
183			```json
184			{
185			"$schema": "./schema/config.json",
186			"guild_id": {}
187			}
188			```
189
190			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.
191
192			If you're using an IDE or editor like [VS Code](https://code.visualstudio.com/) or [WebStorm](https://www.jetbrains.com/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.
193
194			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`.
195
196			## Registering Application Commands
197
198			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:
199
200			```bash
201			node scripts/deploy-commands.js
202			```
203
204			Pass the `--guild` option to register guild commands instead of global commands, and `--clear` to clear all the registered slash commands in the API.
205
206			## Starting the bot
207
208			Now it's time to start the bot. Run the following command to start the bot:
209
210			```bash
211			npm start
212			```
213
214			Or in a production enviroment, it's best to use the following command as it uses the PM2 process manager.
215
216			```bash
217			npm run start:prod
218			```
219
220			Or if you want to see the process output in real time while in a production enviroment you can run the following:
221
222			```bash
223			npm run start:prod -- --no-daemon
224			```
225
226			Or if you are using Bun, you can start the bot up without compilation. To start in dev mode, run the following command:
227
228			```bash
229			bun dev
230			```
231
232			Or if you need to run it in a production enviroment, run the following command:
233
234			```bash
235			bun start:prod
236			```
237
238			Or if you want to see the process output in real time while in a production enviroment you can run the following:
239
240			```bash
241			bun start:prod --no-daemon
242			```
243
244			And if everything was configured correctly, the bot will log in successfully to Discord. Congratulations, you've set up your own instance of SudoBot!
245
246			## Emojis
247
248			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).
249
250			The emojs are freely available for download at the [download site](https://www.onesoftnet.eu.org/downloads/sudo/emojis/). The bot uses some other emojis as well, if you want you can download them from [emoji.gg](https://emoji.gg).
251
252			If you don't add these emojis, the bot may send messages that look weird or too simple.
253
254			## Help & Support
255
256			In case if you're facing issues, feel free to open an issue at [GitHub](https://github.com/onesoft-sudo/sudobot/issues). Or you can contact the Author of the bot in the following ways:
257
258			- Email: [[email protected]](mailto:[email protected])
259			- Discord: [@rakinar2](https://discord.com/users/774553653394538506)
260			- Discord Servers: [OSN's server](https://discord.gg/JJDy9SHzGv)
261
262			Give the repository a star to show your support! We'll be really thankful if you do.