%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

<Callout type="warning">
    This guide assumes you have a Linux/Unix-based system where you'll install SudoBot. Windows users, please [scroll down](#windows-compatibility) to see how you can run SudoBot on Windows.
</Callout>

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

### Building SudoBot for Node.js

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 memory, this command might 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 **v22**, however they should also work with **v20** and **v21**.
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!

### Building SudoBot for Bun

If you'd like to use Bun instead of Node.js to run SudoBot, then you don't need to build the bot because Bun supports TypeScript natively. Just skip to the next part and follow the commands and instructions specifically for Bun.

## 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. This is like a password for
# the bot's internal use.
# On Linux/Unix 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
```

## Windows Compatibility

SudoBot was created with Linux/Unix-based systems in mind, since in most cases you're going to end up running SudoBot on a production server which is usually Linux/Unix-based.
However, that doesn't mean you can't run SudoBot on Windows &mdash; but please keep in mind that some things might need tweaks or you might need to do some things differently to make it work on Windows.

**First of all**, BlazeBuild on Windows is still experimental, known to have some issues. So please run the following commands as alternatives:

**Install dependencies**

```bash
bun install
```

If using Node:

```bash
npm install -D
```

**Build the project (Skip this if using Bun)**

```bash
npm run build
```

**Run the Database Migrations**

Please first make sure you have the right credentials in your `.env` file. Then, create a new file named `migrate.ts` in the project root with the following contents:

```typescript
import "dotenv/config";

const { drizzle } = await import(String("drizzle-orm/node-postgres"));
const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
const { Pool } = await import(String("pg"));

const pool = new Pool({
    connectionString: process.env.DB_URL
});

const db = drizzle(pool);
await migrate(db, { migrationsFolder: "drizzle" });
await pool.end();
```

Then run this file:

```bash
bun migrate.ts
```

And if everything was correctly set up, your database will have the new tables created for SudoBot.

**Starting the Bot**

Be sure to set up the configuration files before starting the bot! After doing that, run the following:

```bash
bun dev
```

Or, if using Node:

```bash
npm run start
```

Also note, to pass any options that you could pass to `./blazew run`, you can just pass it normally to `bun dev` if using `bun`, or after a `--` argument if using `npm run start`.

## 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: [rakinar2@onesoftnet.eu.org](mailto:rakinar2@onesoftnet.eu.org)
-   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	rakinar2	575	---
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	rakinar2	602	<Callout type="warning">
21			This guide assumes you have a Linux/Unix-based system where you'll install SudoBot. Windows users, please [scroll down](#windows-compatibility) to see how you can run SudoBot on Windows.
22			</Callout>
23
24	rakinar2	575	Before you start, you need to have the following installed on your system:
25
26			- 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.
27			- A [PostgreSQL](https://www.postgresql.org/) database server. You can use a local server or use a cloud service like [Supabase](https://supabase.com/).
28
29			Additionally, you can also set these up if you want to use them:
30
31			- 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).
32			- Pixabay API Token to use the `pixabay` command. See [Pixabay's API Docs](https://pixabay.com/api/docs/) for more information.
33			- A Discord Webhook URL for sending error reports.
34			- [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.
35			- [Git](https://git-scm.com/) (optional; to clone the repository)
36
37			Lastly, we expect you to have a very basic understanding of how to use a terminal or command prompt, and how to run commands.
38
39			## Installation
40
41	rakinar2	580	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:
42	rakinar2	575
43			```bash
44			git clone https://github.com/onesoft-sudo/sudobot
45			```
46
47	rakinar2	580	You can also checkout the [svn](https://subversion.apache.org/) repository:
48
49			```bash
50			svn checkout https://svn.onesoftnet.eu.org/svn/sudobot sudobot
51			```
52
53			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).
54	rakinar2	575	Then, extract the downloaded file to a directory of your choice.
55
56			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:
57
58			```bash
59			cd sudobot
60			```
61
62	rakinar2	599	### Building SudoBot for Node.js
63
64	rakinar2	575	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.
65			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.
66			BlazeBuild will also make sure to install any missing SDKs or tools required for building the project.
67
68			The repository already contains the BlazeBuild wrapper (blazew). To build the project, run the following command in your terminal:
69
70			```bash
71			./blazew build
72			```
73
74			This will build, compile and package the project into a `build` directory in the project root, which contains the compiled JavaScript files.
75			Depending on your system, the build process may take a few seconds to a few minutes to complete.
76			We recommend using a system with at least 8GB of RAM and 2 CPU cores for faster build times.
77
78	rakinar2	602	If you don't have enough memory, this command might 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 v22, however they should also work with v20 and v21.
79	rakinar2	575	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.
80			You can download the prebuilt versions in the GitHub releases page: https://github.com/onesoft-sudo/sudobot/releases/latest
81
82			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!
83
84	rakinar2	599	### Building SudoBot for Bun
85
86			If you'd like to use Bun instead of Node.js to run SudoBot, then you don't need to build the bot because Bun supports TypeScript natively. Just skip to the next part and follow the commands and instructions specifically for Bun.
87
88	rakinar2	575	## Configuration
89
90			After building the project, you need to configure the bot to run on your server.
91			You'll need to configure the following:
92
93			- The environment variables
94			- The configuration files
95
96			### Environment Variables
97
98			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.
99
100			Create a new file named `.env` in the project root, and add the following environment variables:
101
102			```bash
103			# Your bot's token from the Discord Developer Portal.
104			TOKEN=your-bot-token
105
106			# Client ID of your bot from the Discord Developer Portal.
107			CLIENT_ID=your-bot-client-id
108
109			# Client Secret of your bot from the Discord Developer Portal.
110			CLIENT_SECRET=your-bot-client-secret
111
112			# The ID of the guild where you want to register the commands,
113			# during development mode, and where the bot will send error reports.
114			# The bot will also search for emojis in this guild.
115			HOME_GUILD_ID=your-home-guild-id
116
117			# Your PostgreSQL database connection URL.
118			# Sometimes your database provider might provide a connection URL
119			# exactly in this format. Otherwise if they give you the details
120			# separately, you can format it to look like this.
121			DB_URL=postgresql://username:password@hostname:port/database
122
123	rakinar2	623	# JWT Secret for generating JWT tokens. This is like a password for
124			# the bot's internal use.
125			# On Linux/Unix systems with OpenSSL installed, you can generate a random
126	rakinar2	575	# secret using the following command:
127			#
128			# openssl rand -base64 32
129			#
130			# Replace `your-jwt-secret` with the generated secret.
131			JWT_SECRET=your-jwt-secret
132
133			# Optionally, you can uncomment the following to turn on debug mode
134			# to see more detailed logs, and enable certain development features.
135
136			# NODE_ENV=development
137			```
138
139			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).
140
141			### Configuration Files
142
143			The bot uses configuration files for storing settings like the bot's prefix, the system administrator IDs, and more.
144			Some of these settings are guild-wide, and some are global.
145			The guild-wide configuration file is `config.json`, and the global system-level configuration file is `system.json`.
146			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.
147			You can edit these files to your liking.
148
149			To see all the possible configuration options, please refer to these schema files:
150
151			- [Guild Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/GuildConfigSchema.ts)
152			- [System Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/SystemConfigSchema.ts)
153
154			## Setting up the Database
155
156			The bot uses a PostgreSQL database to store data like guild settings, user settings, and more.
157
158			To set up the database, make sure you've set the `DB_URL` environment variable in the `.env` file.
159			Then, run the following command in your terminal to run the database migrations:
160
161			```bash
162			./blazew migrate
163			```
164
165			This will create the required tables in the database.
166
167			## Running the Bot
168
169			After configuring the bot, you can run it using the following command:
170
171			```bash
172			./blazew run
173			```
174
175			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:
176
177			```bash
178	rakinar2	593	./blazew run --node
179	rakinar2	575	```
180
181			This will start the bot, and you should see the bot online in your Discord server.
182			Congratulations! You have successfully set up a custom instance of SudoBot on your server 🎉
183
184			## Next steps
185
186			### Registering application commands
187
188			The bot uses [Discord's Application Commands](https://discord.com/developers/docs/interactions/application-commands) for slash commands and context menus.
189			To register the application commands to the Discord API, you can run the following command:
190
191			```bash
192	rakinar2	593	./blazew run -- -u
193	rakinar2	575	```
194
195			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.
196			If you don't have debug mode enabled, the bot will register the commands globally.
197
198			If you want to force the bot to register the commands globally, you can run the following command:
199
200			```bash
201	rakinar2	593	./blazew run -- -u -g
202	rakinar2	575	```
203
204			To clear the registered commands, you can run the following command:
205
206			```bash
207	rakinar2	593	./blazew run -- -c
208	rakinar2	575	```
209
210			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.
211			To force the bot to clear the commands globally, you can run the following command:
212
213			```bash
214	rakinar2	593	./blazew run -- -c -g
215	rakinar2	575	```
216
217	rakinar2	602	## Windows Compatibility
218
219			SudoBot was created with Linux/Unix-based systems in mind, since in most cases you're going to end up running SudoBot on a production server which is usually Linux/Unix-based.
220			However, that doesn't mean you can't run SudoBot on Windows — but please keep in mind that some things might need tweaks or you might need to do some things differently to make it work on Windows.
221
222			First of all, BlazeBuild on Windows is still experimental, known to have some issues. So please run the following commands as alternatives:
223
224			Install dependencies
225
226			```bash
227			bun install
228			```
229
230			If using Node:
231
232			```bash
233			npm install -D
234			```
235
236			Build the project (Skip this if using Bun)
237
238			```bash
239			npm run build
240			```
241
242			Run the Database Migrations
243
244			Please first make sure you have the right credentials in your `.env` file. Then, create a new file named `migrate.ts` in the project root with the following contents:
245
246			```typescript
247			import "dotenv/config";
248
249			const { drizzle } = await import(String("drizzle-orm/node-postgres"));
250			const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
251			const { Pool } = await import(String("pg"));
252
253			const pool = new Pool({
254			connectionString: process.env.DB_URL
255			});
256
257			const db = drizzle(pool);
258			await migrate(db, { migrationsFolder: "drizzle" });
259			await pool.end();
260			```
261
262			Then run this file:
263
264			```bash
265			bun migrate.ts
266			```
267
268			And if everything was correctly set up, your database will have the new tables created for SudoBot.
269
270			Starting the Bot
271
272			Be sure to set up the configuration files before starting the bot! After doing that, run the following:
273
274			```bash
275			bun dev
276			```
277
278			Or, if using Node:
279
280			```bash
281			npm run start
282			```
283
284			Also note, to pass any options that you could pass to `./blazew run`, you can just pass it normally to `bun dev` if using `bun`, or after a `--` argument if using `npm run start`.
285
286	rakinar2	575	## Emojis
287
288			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).
289
290			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).
291
292			If you don't add these emojis, the bot may send messages that look unformatted or broken.
293
294			## Help & Support
295
296			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:
297
298			- Email: [rakinar2@onesoftnet.eu.org](mailto:rakinar2@onesoftnet.eu.org)
299			- Discord: [@rakinar2](https://discord.com/users/774553653394538506)
300			- Discord Servers: [Official OSN Server](https://discord.gg/JJDy9SHzGv)
301
302			Give the repository a star to show your support! We'll be really thankful if you do.
team@onesoftnet.eu.org	ViewVC Help
Powered by ViewVC 1.1.26