/[sudobot]/trunk/docs/app/(docs)/getting-started/page.mdx
ViewVC logotype

Annotation of /trunk/docs/app/(docs)/getting-started/page.mdx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 632 - (hide annotations)
Thu Oct 10 17:53:11 2024 UTC (5 months, 2 weeks ago) by rakinar2
File size: 14205 byte(s)
chore: synchronize

1 rakinar2 575 ---
2 rakinar2 626 title: Getting Started
3 rakinar2 575 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 632 Before you start, you need to have the following:
25 rakinar2 575
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 rakinar2 626 # The directory where the bot will store persistent data like
134     # configuration files, logs, and more.
135     SUDO_PREFIX=/path/to/sudobot/storage
136    
137 rakinar2 575 # Optionally, you can uncomment the following to turn on debug mode
138     # to see more detailed logs, and enable certain development features.
139    
140     # NODE_ENV=development
141     ```
142    
143     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).
144    
145     ### Configuration Files
146    
147     The bot uses configuration files for storing settings like the bot's prefix, the system administrator IDs, and more.
148     Some of these settings are guild-wide, and some are global.
149     The guild-wide configuration file is `config.json`, and the global system-level configuration file is `system.json`.
150     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.
151     You can edit these files to your liking.
152    
153 rakinar2 626 Then, go to the `SUDO_PREFIX` directory, and copy the `config` directory to the `SUDO_PREFIX` directory.
154     This should also copy the `config.json` and `system.json` files to the `SUDO_PREFIX` directory, that you just edited.
155    
156     **Remember, this step is important. Otherwise, any updates to the configuration files will be lost when you update the bot using Git.**
157    
158 rakinar2 575 To see all the possible configuration options, please refer to these schema files:
159    
160     - [Guild Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/GuildConfigSchema.ts)
161     - [System Configuration Schema](https://github.com/onesoft-sudo/sudobot/blob/main/src/main/typescript/schemas/SystemConfigSchema.ts)
162    
163     ## Setting up the Database
164    
165     The bot uses a PostgreSQL database to store data like guild settings, user settings, and more.
166    
167     To set up the database, make sure you've set the `DB_URL` environment variable in the `.env` file.
168     Then, run the following command in your terminal to run the database migrations:
169    
170     ```bash
171     ./blazew migrate
172     ```
173    
174     This will create the required tables in the database.
175    
176     ## Running the Bot
177    
178     After configuring the bot, you can run it using the following command:
179    
180     ```bash
181     ./blazew run
182     ```
183    
184     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:
185    
186     ```bash
187 rakinar2 593 ./blazew run --node
188 rakinar2 575 ```
189    
190     This will start the bot, and you should see the bot online in your Discord server.
191     Congratulations! You have successfully set up a custom instance of SudoBot on your server 🎉
192    
193     ## Next steps
194    
195     ### Registering application commands
196    
197     The bot uses [Discord's Application Commands](https://discord.com/developers/docs/interactions/application-commands) for slash commands and context menus.
198     To register the application commands to the Discord API, you can run the following command:
199    
200     ```bash
201 rakinar2 593 ./blazew run -- -u
202 rakinar2 575 ```
203    
204     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.
205     If you don't have debug mode enabled, the bot will register the commands globally.
206    
207     If you want to force the bot to register the commands globally, you can run the following command:
208    
209     ```bash
210 rakinar2 593 ./blazew run -- -u -g
211 rakinar2 575 ```
212    
213     To clear the registered commands, you can run the following command:
214    
215     ```bash
216 rakinar2 593 ./blazew run -- -c
217 rakinar2 575 ```
218    
219     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.
220     To force the bot to clear the commands globally, you can run the following command:
221    
222     ```bash
223 rakinar2 593 ./blazew run -- -c -g
224 rakinar2 575 ```
225    
226 rakinar2 602 ## Windows Compatibility
227    
228     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.
229     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.
230    
231     **First of all**, BlazeBuild on Windows is still experimental, known to have some issues. So please run the following commands as alternatives:
232    
233     **Install dependencies**
234    
235     ```bash
236     bun install
237     ```
238    
239     If using Node:
240    
241     ```bash
242     npm install -D
243     ```
244    
245 rakinar2 626 You might get an error saying something like `symlink(): Operation not permitted` &mdash; this is fine and you can safely ignore it.
246    
247 rakinar2 602 **Build the project (Skip this if using Bun)**
248    
249     ```bash
250     npm run build
251     ```
252    
253 rakinar2 626 **Copy the resource files**
254    
255     Please copy the following resources from `src` to `build`:
256    
257     * `src/main/resources` should be copied to `build/out/main` and the name should still be `resources`
258    
259 rakinar2 602 **Run the Database Migrations**
260    
261     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:
262    
263     ```typescript
264     import "dotenv/config";
265    
266     const { drizzle } = await import(String("drizzle-orm/node-postgres"));
267     const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
268     const { Pool } = await import(String("pg"));
269    
270     const pool = new Pool({
271     connectionString: process.env.DB_URL
272     });
273    
274     const db = drizzle(pool);
275     await migrate(db, { migrationsFolder: "drizzle" });
276     await pool.end();
277     ```
278    
279     Then run this file:
280    
281     ```bash
282     bun migrate.ts
283     ```
284    
285 rakinar2 626 If you'd like to use Node.js for this, then create a `migrate.js` file instead and paste the following:
286    
287     ```javascript
288     require("dotenv/config");
289    
290     async function main() {
291     const { drizzle } = await import(String("drizzle-orm/node-postgres"));
292     const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
293     const { Pool } = await import(String("pg"));
294    
295     const pool = new Pool({
296     connectionString: process.env.DB_URL
297     });
298    
299     const db = drizzle(pool);
300     await migrate(db, { migrationsFolder: "drizzle" });
301     await pool.end();
302     }
303    
304     main();
305     ```
306    
307     And run:
308    
309     ```bash
310     node migrate.js
311     ```
312    
313 rakinar2 602 And if everything was correctly set up, your database will have the new tables created for SudoBot.
314    
315     **Starting the Bot**
316    
317     Be sure to set up the configuration files before starting the bot! After doing that, run the following:
318    
319     ```bash
320     bun dev
321     ```
322    
323     Or, if using Node:
324    
325     ```bash
326     npm run start
327     ```
328    
329     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`.
330    
331 rakinar2 575 ## Emojis
332    
333     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).
334    
335     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).
336    
337     If you don't add these emojis, the bot may send messages that look unformatted or broken.
338    
339     ## Help & Support
340    
341     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:
342    
343     - Email: [[email protected]](mailto:[email protected])
344     - Discord: [@rakinar2](https://discord.com/users/774553653394538506)
345 rakinar2 626 - Discord Servers: [Official OSN Server](https://sudobot.online/discord)
346 rakinar2 575
347     Give the repository a star to show your support! We'll be really thankful if you do.

[email protected]
ViewVC Help
Powered by ViewVC 1.1.26