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

---
title: Getting Started - SudoBot
short_name: Getting Started
---

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

# Getting Started

This guide will help you get started with SudoBot. You will learn how to build the bot from source, configure and run it on your own server, 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>

## Prerequisites

Before you start, you need to have the following installed on your system:

- A Discord API Application token (bot token). Go to the [Discord Developer Portal](https://discord.com/developers/applications) to create a new application, and get the token.
- A [PostgreSQL](https://www.postgresql.org/) database server. You can use a local server or use a cloud service like [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. See [Pixabay's API Docs](https://pixabay.com/api/docs/) for more information.
-   A Discord Webhook URL for sending error reports.
- [Node.js](https://nodejs.org/) (v21 or higher) or [Bun](https://bun.sh) (v1.1.12 or higher). These will be installed automatically if you don't install them, during the build process.
- [Git](https://git-scm.com/) (optional; to clone the repository)

Lastly, we expect you to have a very basic understanding of how to use a terminal or command prompt, and how to run commands.

## Installation

To install SudoBot, you need to clone the [git](https://git-scm.com) repository or checkout the [svn](https://subversion.apache.org/) repository first, if you have git installed. Run the following command in your terminal:

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

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

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

If you don't have git or svn installed, you can download the repository as a zipball/tarball from the [GitHub Releases Page](https://github.com/onesoft-sudo/sudobot/releases/latest).
Then, extract the downloaded file to a directory of your choice.

Next, navigate to the directory where you have cloned the repository using Git, or extracted the zipball/tarball, by running the following command in your terminal:

```bash
cd sudobot
```

Now, to build the project, we'll use [BlazeBuild](https://github.com/onesoft-sudo/sudobot/tree/main/blazebuild), which is a blazingly fast build tool, for TypeScript and JavaScript projects.
To use BlazeBuild, you don't need to install anything including BlazeBuild itself, as it will be installed and set-up automatically during the build process.
BlazeBuild will also make sure to install any missing SDKs or tools required for building the project.

The repository already contains the BlazeBuild wrapper (blazew). To build the project, run the following command in your terminal:

```bash
./blazew build
```

This will build, compile and package the project into a `build` directory in the project root, which contains the compiled JavaScript files.
Depending on your system, the build process may take a few seconds to a few minutes to complete.
We recommend using a system with at least 8GB of RAM and 2 CPU cores for faster build times.

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!

## Configuration

After building the project, you need to configure the bot to run on your server.
You'll need to configure the following:

- The environment variables
- The configuration files

### Environment Variables

The bot uses environment variables for storing secret credentials like your bot's token. You can set these in a `.env` file in the project root.

Create a new file named `.env` in the project root, and add the following environment variables:

```bash
# Your bot's token from the Discord Developer Portal.
TOKEN=your-bot-token

# Client ID of your bot from the Discord Developer Portal.
CLIENT_ID=your-bot-client-id

# Client Secret of your bot from the Discord Developer Portal.
CLIENT_SECRET=your-bot-client-secret

# The ID of the guild where you want to register the commands,
# during development mode, and where the bot will send error reports.
# The bot will also search for emojis in this guild.
HOME_GUILD_ID=your-home-guild-id

# Your PostgreSQL database connection URL.
# Sometimes your database provider might provide a connection URL 
# exactly in this format. Otherwise if they give you the details
# separately, you can format it to look like this.
DB_URL=postgresql://username:password@hostname:port/database

# JWT Secret for generating JWT tokens.
# On systems with openssl installed, you can generate a random 
# secret using the following command:
#
#    openssl rand -base64 32
#
# Replace `your-jwt-secret` with the generated secret.
JWT_SECRET=your-jwt-secret

# Optionally, you can uncomment the following to turn on debug mode 
# to see more detailed logs, and enable certain development features.

# NODE_ENV=development
```

There are a lot of other environment variables that you can set, but these are the most important ones. You can check out all the environment variables in the [environment variable schema file](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/EnvironmentVariableSchema.ts).

### Configuration Files

The bot uses configuration files for storing settings like the bot's prefix, the system administrator IDs, and more.
Some of these settings are guild-wide, and some are global.
The guild-wide configuration file is `config.json`, and the global system-level configuration file is `system.json`.
The files are located at `config/` in the project root. These configuration files don't contain any specific setting, they are just a starting point for you to configure the bot.
You can edit these files to your liking.

To see all the possible configuration options, please refer to these schema files:

- [Guild Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/GuildConfigSchema.ts)
- [System Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/SystemConfigSchema.ts)

## Setting up the Database

The bot uses a PostgreSQL database to store data like guild settings, user settings, and more.

To set up the database, make sure you've set the `DB_URL` environment variable in the `.env` file.
Then, run the following command in your terminal to run the database migrations:

```bash
./blazew migrate
```

This will create the required tables in the database.

## Running the Bot

After configuring the bot, you can run it using the following command:

```bash
./blazew run
```

By default, BlazeBuild will use [Bun](https://bun.sh) to run the bot. If you want to use Node.js instead, you can run the following command:

```bash
./blazew run -- --node
```

This will start the bot, and you should see the bot online in your Discord server. 
Congratulations! You have successfully set up a custom instance of SudoBot on your server 🎉

## Next steps

### Registering application commands

The bot uses [Discord's Application Commands](https://discord.com/developers/docs/interactions/application-commands) for slash commands and context menus.
To register the application commands to the Discord API, you can run the following command:

```bash
./blazew run -- -- -u
```

If you have debug mode enabled and have `HOME_GUILD_ID` set in the `.env` file, the bot will register the commands in the development guild.
If you don't have debug mode enabled, the bot will register the commands globally.

If you want to force the bot to register the commands globally, you can run the following command:

```bash
./blazew run -- -- -u -g
```

To clear the registered commands, you can run the following command:

```bash
./blazew run -- -- -c
```

Once again, if you have debug mode enabled, the bot will clear the commands in the development guild. Otherwise, it will clear the commands globally.
To force the bot to clear the commands globally, you can run the following command:

```bash
./blazew run -- -- -c -g
```

## 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 emojis are freely available for download at the [download server](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 unformatted or broken.

## 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: [Official OSN Server](https://discord.gg/JJDy9SHzGv)

Give the repository a star to show your support! We'll be really thankful if you do.
1	---
2	title: Getting Started - SudoBot
3	short_name: Getting Started
4	---
5
6	import Callout from "@/components/Alerts/Callout";
7
8	# Getting Started
9
10	This guide will help you get started with SudoBot. You will learn how to build the bot from source, configure and run it on your own server, 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	## Prerequisites
19
20	Before you start, you need to have the following installed on your system:
21
22	- A Discord API Application token (bot token). Go to the [Discord Developer Portal](https://discord.com/developers/applications) to create a new application, and get the token.
23	- A [PostgreSQL](https://www.postgresql.org/) database server. You can use a local server or use a cloud service like [Supabase](https://supabase.com/).
24
25	Additionally, you can also set these up if you want to use them:
26
27	- 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).
28	- Pixabay API Token to use the `pixabay` command. See [Pixabay's API Docs](https://pixabay.com/api/docs/) for more information.
29	- A Discord Webhook URL for sending error reports.
30	- [Node.js](https://nodejs.org/) (v21 or higher) or [Bun](https://bun.sh) (v1.1.12 or higher). These will be installed automatically if you don't install them, during the build process.
31	- [Git](https://git-scm.com/) (optional; to clone the repository)
32
33	Lastly, we expect you to have a very basic understanding of how to use a terminal or command prompt, and how to run commands.
34
35	## Installation
36
37	To install SudoBot, you need to clone the [git](https://git-scm.com) repository or checkout the [svn](https://subversion.apache.org/) repository first, if you have git installed. Run the following command in your terminal:
38
39	```bash
40	git clone https://github.com/onesoft-sudo/sudobot
41	```
42
43	You can also checkout the [svn](https://subversion.apache.org/) repository:
44
45	```bash
46	svn checkout https://svn.onesoftnet.eu.org/svn/sudobot sudobot
47	```
48
49	If you don't have git or svn installed, you can download the repository as a zipball/tarball from the [GitHub Releases Page](https://github.com/onesoft-sudo/sudobot/releases/latest).
50	Then, extract the downloaded file to a directory of your choice.
51
52	Next, navigate to the directory where you have cloned the repository using Git, or extracted the zipball/tarball, by running the following command in your terminal:
53
54	```bash
55	cd sudobot
56	```
57
58	Now, to build the project, we'll use [BlazeBuild](https://github.com/onesoft-sudo/sudobot/tree/main/blazebuild), which is a blazingly fast build tool, for TypeScript and JavaScript projects.
59	To use BlazeBuild, you don't need to install anything including BlazeBuild itself, as it will be installed and set-up automatically during the build process.
60	BlazeBuild will also make sure to install any missing SDKs or tools required for building the project.
61
62	The repository already contains the BlazeBuild wrapper (blazew). To build the project, run the following command in your terminal:
63
64	```bash
65	./blazew build
66	```
67
68	This will build, compile and package the project into a `build` directory in the project root, which contains the compiled JavaScript files.
69	Depending on your system, the build process may take a few seconds to a few minutes to complete.
70	We recommend using a system with at least 8GB of RAM and 2 CPU cores for faster build times.
71
72	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.
73	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.
74	You can download the prebuilt versions in the GitHub releases page: https://github.com/onesoft-sudo/sudobot/releases/latest
75
76	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!
77
78	## Configuration
79
80	After building the project, you need to configure the bot to run on your server.
81	You'll need to configure the following:
82
83	- The environment variables
84	- The configuration files
85
86	### Environment Variables
87
88	The bot uses environment variables for storing secret credentials like your bot's token. You can set these in a `.env` file in the project root.
89
90	Create a new file named `.env` in the project root, and add the following environment variables:
91
92	```bash
93	# Your bot's token from the Discord Developer Portal.
94	TOKEN=your-bot-token
95
96	# Client ID of your bot from the Discord Developer Portal.
97	CLIENT_ID=your-bot-client-id
98
99	# Client Secret of your bot from the Discord Developer Portal.
100	CLIENT_SECRET=your-bot-client-secret
101
102	# The ID of the guild where you want to register the commands,
103	# during development mode, and where the bot will send error reports.
104	# The bot will also search for emojis in this guild.
105	HOME_GUILD_ID=your-home-guild-id
106
107	# Your PostgreSQL database connection URL.
108	# Sometimes your database provider might provide a connection URL
109	# exactly in this format. Otherwise if they give you the details
110	# separately, you can format it to look like this.
111	DB_URL=postgresql://username:password@hostname:port/database
112
113	# JWT Secret for generating JWT tokens.
114	# On systems with openssl installed, you can generate a random
115	# secret using the following command:
116	#
117	# openssl rand -base64 32
118	#
119	# Replace `your-jwt-secret` with the generated secret.
120	JWT_SECRET=your-jwt-secret
121
122	# Optionally, you can uncomment the following to turn on debug mode
123	# to see more detailed logs, and enable certain development features.
124
125	# NODE_ENV=development
126	```
127
128	There are a lot of other environment variables that you can set, but these are the most important ones. You can check out all the environment variables in the [environment variable schema file](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/EnvironmentVariableSchema.ts).
129
130	### Configuration Files
131
132	The bot uses configuration files for storing settings like the bot's prefix, the system administrator IDs, and more.
133	Some of these settings are guild-wide, and some are global.
134	The guild-wide configuration file is `config.json`, and the global system-level configuration file is `system.json`.
135	The files are located at `config/` in the project root. These configuration files don't contain any specific setting, they are just a starting point for you to configure the bot.
136	You can edit these files to your liking.
137
138	To see all the possible configuration options, please refer to these schema files:
139
140	- [Guild Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/GuildConfigSchema.ts)
141	- [System Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/SystemConfigSchema.ts)
142
143	## Setting up the Database
144
145	The bot uses a PostgreSQL database to store data like guild settings, user settings, and more.
146
147	To set up the database, make sure you've set the `DB_URL` environment variable in the `.env` file.
148	Then, run the following command in your terminal to run the database migrations:
149
150	```bash
151	./blazew migrate
152	```
153
154	This will create the required tables in the database.
155
156	## Running the Bot
157
158	After configuring the bot, you can run it using the following command:
159
160	```bash
161	./blazew run
162	```
163
164	By default, BlazeBuild will use [Bun](https://bun.sh) to run the bot. If you want to use Node.js instead, you can run the following command:
165
166	```bash
167	./blazew run -- --node
168	```
169
170	This will start the bot, and you should see the bot online in your Discord server.
171	Congratulations! You have successfully set up a custom instance of SudoBot on your server 🎉
172
173	## Next steps
174
175	### Registering application commands
176
177	The bot uses [Discord's Application Commands](https://discord.com/developers/docs/interactions/application-commands) for slash commands and context menus.
178	To register the application commands to the Discord API, you can run the following command:
179
180	```bash
181	./blazew run -- -- -u
182	```
183
184	If you have debug mode enabled and have `HOME_GUILD_ID` set in the `.env` file, the bot will register the commands in the development guild.
185	If you don't have debug mode enabled, the bot will register the commands globally.
186
187	If you want to force the bot to register the commands globally, you can run the following command:
188
189	```bash
190	./blazew run -- -- -u -g
191	```
192
193	To clear the registered commands, you can run the following command:
194
195	```bash
196	./blazew run -- -- -c
197	```
198
199	Once again, if you have debug mode enabled, the bot will clear the commands in the development guild. Otherwise, it will clear the commands globally.
200	To force the bot to clear the commands globally, you can run the following command:
201
202	```bash
203	./blazew run -- -- -c -g
204	```
205
206	## Emojis
207
208	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).
209
210	The emojis are freely available for download at the [download server](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).
211
212	If you don't add these emojis, the bot may send messages that look unformatted or broken.
213
214	## Help & Support
215
216	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:
217
218	- Email: [[email protected]](mailto:[email protected])
219	- Discord: [@rakinar2](https://discord.com/users/774553653394538506)
220	- Discord Servers: [Official OSN Server](https://discord.gg/JJDy9SHzGv)
221
222	Give the repository a star to show your support! We'll be really thankful if you do.