/[sudobot]/branches/9.x-dev/docs/app/(docs)/getting-started/page.mdx
ViewVC logotype

Annotation of /branches/9.x-dev/docs/app/(docs)/getting-started/page.mdx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 577 - (hide annotations)
Mon Jul 29 18:52:37 2024 UTC (8 months, 1 week ago) by rakinar2
File size: 11105 byte(s)
chore: add old version archive branches (2.x to 9.x-dev)
1 rakinar2 577 ---
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     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     ## Requirements
19    
20     These are the requirements to host SudoBot:
21    
22     - A Discord API Application token (Go to [Discord Developer Portal](https://discord.com/developers/applications) to obtain a token)
23     - [Node.js](https://nodejs.org) version 18 or higher
24     - A PostgreSQL database (If you're looking for a free PostgreSQL hosting service, check out [Neon](https://neon.tech))
25    
26     Additionally, you can also set these up if you want to use them:
27    
28     - 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))
29     - Pixabay API Token to use the `pixabay` command (can be obtained [here](https://pixabay.com/api/docs/))
30     - A Discord Webhook URL for sending error reports
31    
32     ## Cloning the project and setting up
33    
34     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.
35    
36     To clone the repository, run this command:
37    
38     ```bash
39     git clone https://github.com/onesoft-sudo/sudobot
40     ```
41    
42     After this command completes, go inside of the directory. (`sudobot/` if you cloned it using the above command)
43    
44     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.
45    
46     ```bash
47     git switch 8.x && git pull origin 8.x
48     ```
49    
50     That command will switch you to 8.x and pull the latest updates from there.
51    
52     Once that is done, install the dependencies using the following command:
53    
54     ```bash
55     npm install -D
56     ```
57    
58     Or, if you prefer using bun over NPM, you run the following command to install the dependencies:
59    
60     ```bash
61     bun install -D
62     ```
63    
64     ## Building the bot
65    
66     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:
67    
68     ```bash
69     npm run build
70     ```
71    
72     Or if you're using bun, you can run the following command to build the bot:
73    
74     ```bash
75     bun run build
76     ```
77    
78     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**.
79     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     ## JSON Configuration Schema
85    
86     Generate the JSON config schema files using the following command:
87    
88     ```bash
89     npm run gen:schema
90     ```
91    
92     You can skip this step and move onto the enviroment variables section if you don't mind not having autocompletion in your IDE/editor.
93    
94     ## The environment variables
95    
96     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)
97    
98     Then you need to add a few variables to `.env` file:
99    
100     ```bash
101     # This is your bot's token.
102     TOKEN=
103    
104     # This is the home server, where the bot will search for emojis.
105     HOME_GUILD_ID=
106    
107     # The client ID of your bot application.
108     CLIENT_ID=
109    
110     # Database URL
111     DB_URL=
112     ```
113    
114     Here:
115    
116     - `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).
117     - `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/).
118     - `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).
119     - `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.
120    
121     A few more environment variables can be specified:
122    
123     - `DEBUG`: Used by the [Prisma](https://prisma.io/) ORM. This enables extra debug logging, aka Verbose Mode.
124     - `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.
125     - `CAT_API_TOKEN`: The Cat API token to use when fetching cat images, using `cat` command.
126     - `DOG_API_TOKEN`: The Dog API token to use when fetching dog images, using `dog` command.
127    
128     ## Setting up a Database for the bot
129    
130     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**.
131    
132     <Callout type="warning">
133     As of November 28, 2023, we no longer officially support MySQL as a database
134     for being used with SudoBot. Please migrate to PostgreSQL.
135     </Callout>
136    
137     <Callout type="info">
138     If you want a free PostgreSQL hosting service, check out
139     [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.
140     </Callout>
141    
142     Your database URL should look like this if you're using PostgreSQL:
143    
144     ```
145     postgresql://username:password@hostname:port/dbname
146     ```
147    
148     - `username` is your database username (usually this is `postgres`)
149     - `password` is your database password
150     - `hostname` is your database hostname
151     - `port` is your database port (usually this is `5432`)
152     - `dbname` is your database name (usually this is `postgres`)
153    
154     After you have set the database URL inside `.env`, you can run the following command:
155    
156     ```bash
157     npx prisma db push
158     ```
159    
160     This will create the necessary tables for you inside the database.
161    
162     ## Configuration
163    
164     Now it's time to configure the bot. Now, SudoBot comes with the config files bundled already, but you should edit them.
165    
166     **Step 1.** Open up `config/config.json` and you have two options:
167    
168     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,
169    
170     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:
171    
172     ```json
173     {
174     "$schema": "./schema/config.json",
175     "guild_id": {}
176     }
177     ```
178    
179     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.
180    
181     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.
182    
183     **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`.
184    
185     ## Registering Application Commands
186    
187     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:
188    
189     ```bash
190     node scripts/deploy-commands.js
191     ```
192    
193     Pass the `--guild` option to register guild commands instead of global commands, and `--clear` to clear all the registered slash commands in the API.
194    
195     ## Starting the bot
196    
197     Now it's time to start the bot. Run the following command to start the bot:
198    
199     ```bash
200     npm start
201     ```
202    
203     Or in a production enviroment, it's best to use the following command as it uses the PM2 process manager.
204    
205     ```bash
206     npm run start:prod
207     ```
208    
209     Or if you want to see the process output in real time while in a production enviroment you can run the following:
210    
211     ```bash
212     npm run start:prod -- --no-daemon
213     ```
214    
215     Or if you are using Bun, you can start the bot up without compilation. To start in dev mode, run the following command:
216    
217     ```bash
218     bun dev
219     ```
220    
221     Or if you need to run it in a production enviroment, run the following command:
222    
223     ```bash
224     bun start:prod
225     ```
226    
227     Or if you want to see the process output in real time while in a production enviroment you can run the following:
228    
229     ```bash
230     bun start:prod --no-daemon
231     ```
232    
233     And if everything was configured correctly, the bot will log in successfully to Discord. Congratulations, you've set up your own instance of SudoBot!
234    
235     ## Emojis
236    
237     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).
238    
239     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).
240    
241     If you don't add these emojis, the bot may send messages that look weird or too simple.
242    
243     ## Help & Support
244    
245     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:
246    
247     - Email: [[email protected]](mailto:[email protected])
248     - Discord: [@rakinar2](https://discord.com/users/774553653394538506)
249     - Discord Servers: [OSN's server](https://discord.gg/JJDy9SHzGv)
250    
251     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