5.x/docs/getting-started.md

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

{% hint style="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. Your Discord server should have at least 50 members to be eligible.
{% endhint %}

## 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 MySQL or PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out [Supabase](https://supabase.com))

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 using [git](https://git-scm.com) or download the [latest release](https://github.com/onesoft-sudo/sudobot/releases/latest) and extract it.

To clone the repository, run this command:

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

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

Then, install the dependencies using the following command:

```
npm install -D
```

Generate the JSON config schema files using the following command:

```
npx ts-node scripts/generate-config-schema.ts
```

## 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](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 the following databases:

* PostgreSQL (Recommended)
* MySQL

{% hint style="info" %}
If you want a free PostgreSQL hosting service, check out [Supabase](https://supabase.com/). It's easy to set up, and completely free of cost.
{% endhint %}

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`)

MySQL database URLs will be almost similar, except the protocol will be `mysql://` instead of `postgresql://` and the port will be `3306` instead of `5432`.

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.ts` (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:

```
{
    "$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:

```
npx ts-node scripts/deploy-commands.ts
```

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

## Building the bot

Now that we have configured the bot and specified every setting, we can go ahead an invoke the TypeScript compiler (`tsc`) to build the bot and generate compiled JavaScript files that the NodeJS interpreter can run. To compile the bot, simply run:

```
npm run build
```

## Starting the bot

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

```
npm start
```

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).&#x20;

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).&#x20;

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: [Silly Cats](https://discord.gg/sillycats), [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	577	# Getting Started
2
3			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.
4
5			{% hint style="info" %}
6			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. Your Discord server should have at least 50 members to be eligible.
7			{% endhint %}
8
9			## Requirements
10
11			These are the requirements to host SudoBot:
12
13			* A Discord API Application token (Go to [Discord Developer Portal](https://discord.com/developers/applications) to obtain a token)
14			* [Node.js](https://nodejs.org) version 18 or higher
15			* A MySQL or PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out [Supabase](https://supabase.com))
16
17			Additionally, you can also set these up if you want to use them:
18
19			* 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))
20			* Pixabay API Token to use the `pixabay` command (can be obtained [here](https://pixabay.com/api/docs/))
21			* A Discord Webhook URL for sending error reports
22
23			## Cloning the project and setting up
24
25			First of all, clone the repository using [git](https://git-scm.com) or download the [latest release](https://github.com/onesoft-sudo/sudobot/releases/latest) and extract it.
26
27			To clone the repository, run this command:
28
29			```
30			git clone https://github.com/onesoft-sudo/sudobot
31			```
32
33			After this command completes, go inside of the directory. (`sudobot/` if you cloned it using the above command)
34
35			Then, install the dependencies using the following command:
36
37			```
38			npm install -D
39			```
40
41			Generate the JSON config schema files using the following command:
42
43			```
44			npx ts-node scripts/generate-config-schema.ts
45			```
46
47			## The environment variables
48
49			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)
50
51			Then you need to add a few variables to `.env` file:
52
53			```
54			# This is your bot's token.
55			TOKEN=
56
57			# This is the home server, where the bot will search for emojis.
58			HOME_GUILD_ID=
59
60			# The client ID of your bot application.
61			CLIENT_ID=
62
63			# Database URL
64			DB_URL=
65			```
66
67			Here:
68
69			* `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).
70			* `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/).
71			* `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).
72			* `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.
73
74			A few more environment variables can be specified:
75
76			* `DEBUG`: Used by the [Prisma](https://prisma.io/) ORM. This enables extra debug logging, aka Verbose Mode.
77			* `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.
78			* `CAT_API_TOKEN`: The Cat API token to use when fetching cat images, using `cat` command.
79			* `DOG_API_TOKEN`: The Dog API token to use when fetching dog images, using `dog` command.
80
81			## Setting up a Database for the bot
82
83			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 the following databases:
84
85			* PostgreSQL (Recommended)
86			* MySQL
87
88			{% hint style="info" %}
89			If you want a free PostgreSQL hosting service, check out [Supabase](https://supabase.com/). It's easy to set up, and completely free of cost.
90			{% endhint %}
91
92			Your database URL should look like this if you're using PostgreSQL:
93
94			```
95			postgresql://username:password@hostname:port/dbname
96			```
97
98			* `username` is your database username (usually this is `postgres`)
99			* `password` is your database password
100			* `hostname` is your database hostname
101			* `port` is your database port (usually this is `5432`)
102			* `dbname` is your database name (usually this is`postgres`)
103
104			MySQL database URLs will be almost similar, except the protocol will be `mysql://` instead of `postgresql://` and the port will be `3306` instead of `5432`.
105
106			After you have set the database URL inside `.env`, you can run the following command:
107
108			```
109			npx prisma db push
110			```
111
112			This will create the necessary tables for you inside the database.
113
114			## Configuration
115
116			Now it's time to configure the bot. Now, SudoBot comes with the config files bundled already, but you should edit them.
117
118			Step 1. Open up `config/config.json` and you have two options:
119
120			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,
121
122			Manually set the settings inside of the file. If you're following along this documentation and have run the script `generate-config-schema.ts` (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:
123
124			```
125			{
126			"$schema": "./schema/config.json",
127			"guild_id": {
128
129			}
130			}
131			```
132
133			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.
134
135			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.
136
137			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`.
138
139			## Registering Application Commands
140
141			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:
142
143			```
144			npx ts-node scripts/deploy-commands.ts
145			```
146
147			Pass the `--guild` option to register guild commands instead of global commands, and `--clear` to clear all the registered slash commands in the API.
148
149			## Building the bot
150
151			Now that we have configured the bot and specified every setting, we can go ahead an invoke the TypeScript compiler (`tsc`) to build the bot and generate compiled JavaScript files that the NodeJS interpreter can run. To compile the bot, simply run:
152
153			```
154			npm run build
155			```
156
157			## Starting the bot
158
159			Now it's time to start the bot. Run the following command to start the bot:
160
161			```
162			npm start
163			```
164
165			And if everything was configured correctly, the bot will log in successfully to Discord. Congratulations, you've set up your own instance of SudoBot!
166
167			## Emojis
168
169			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).
170
171			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).
172
173			If you don't add these emojis, the bot may send messages that look weird or too simple.
174
175			## Help & Support
176
177			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:
178
179			* Email: [[email protected]](mailto:[email protected])
180			* Discord: [@rakinar2](https://discord.com/users/774553653394538506)
181			* Discord Servers: [Silly Cats](https://discord.gg/sillycats), [OSN's server](https://discord.gg/JJDy9SHzGv)
182
183			Give the repository a star to show your support! We'll be really thankful if you do.