murm/mrmBot-Matrix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Move wiki inside repo

Browse source
This commit is contained in:
Essem 2022-06-24 18:04:05 -05:00
parent 2112e93684
commit d469d36a59
No known key found for this signature in database
GPG key ID: 7D497397CC3A2A8C
7 changed files with 384 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
.github/workflows/build.yml vendored
View file

@ -35,6 +35,10 @@ jobs:
uses: actions/checkout@v1
- name: Setup MSYS2
uses: msys2/setup-msys2@v2
with:
msystem: MINGW64
update: true
install: git mingw-w64-x86_64-cc mingw-w64-x86_64-libvips mingw-w64-x86_64-imagemagick
- name: Setup Node.js environment
uses: actions/setup-node@v2.1.2
with:
@ -43,9 +47,6 @@ jobs:
uses: pnpm/action-setup@v2.2.2
with:
version: 7
- name: Install dependencies
shell: msys2 {0}
run: pacman -S --noconfirm mingw-w64-x86_64-libvips mingw-w64-x86_64-imagemagick
- name: Build
shell: msys2 {0}
run: $PNPM_HOME/pnpm install --config.strict-peer-dependencies=false && $PNPM_HOME/pnpm run build

2
README.md
View file

@ -11,7 +11,7 @@ You can invite the bot to your server using this link: https://projectlounge.pw/
A command list can be found [here](https://projectlounge.pw/esmBot/help.html).
If you want to self-host the bot, a guide can be found [here](https://github.com/esmBot/esmBot/wiki/Setup).
If you want to self-host the bot, a guide can be found [here](https://github.com/esmBot/esmBot/blob/master/docs/setup.md).
## Credits
Icon by [Steel](https://twitter.com/MintBurrow).

19
docs/config.md Normal file
View file

@ -0,0 +1,19 @@
# Config
esmBot uses environment variables for configuration. To make managing them easier, a `.env` file is included with the bot and can be used to load the variables on bot startup.
Here's an overview of the environment variables required to run the bot:
- `NODE_ENV`: Used for tuning the bot to different environments. If you don't know what to set it to, leave it as is.
- `TOKEN`: Your bot's token. You can find this at https://discord.com/developers/applications under your application's Bot tab.
- `DB`: The database connection string. By default the `sqlite` and `postgresql` protocols are available, but this can be expanded by putting proper DB driver scripts into `utils/database/`. You can also set this to `dummy` to make the bot not use a database at all.
- `OWNER`: Your Discord user ID. This is used for granting yourself access to certain management commands. Adding multiple users is supported by separating the IDs with a comma; however, this is not recommended for security purposes.
- `PREFIX`: The bot's default command prefix. Note that servers can set their own individual prefixes via the `prefix` command.
Here's an overview of the variables that are not necessarily required for the bot to run, but can greatly enhance its functionality:
- `STAYVC`: Set this to true if you want the bot to stay in voice chat after playing music/a sound effect. You can make it leave by using the stop command.
- `DBL`: An API token from [Top.gg](https://top.gg/). Unnecessary for most users since Top.gg tends to ban forks of bots like esmBot from their list.
- `TENOR`: An API token from [Tenor](https://tenor.com/gifapi). This is not required for using GIFs from Tenor; however, it can greatly reduce resource usage from converting said GIFs.
- `OUTPUT`: A directory to output the help documentation in Markdown format to. It's recommended to set this to a directory being served by a web server.
- `TEMPDIR`: A directory that will store generated images larger than 8MB. It's recommended to set this to a directory being served by a web server.
- `TMP_DOMAIN`: The root domain/directory that the images larger than 8MB are stored at. Example: `https://projectlounge.pw/tmp`
- `METRICS`: The HTTP port to serve [Prometheus](https://prometheus.io/)-compatible metrics on.
- `API`: Set this to true if you plan on using the image API. Images will be requested from the URLs specified in the `image` block of `servers.json`.

66
docs/custom-commands.md Normal file
View file

@ -0,0 +1,66 @@
# Custom Commands
esmBot has a flexible command handler, allowing you to create new commands and categories simply by creating new files. This page will provide a reference for creating new commands.
## Directory Structure
The bot loads commands from subdirectories inside of the `commands` directory, which looks something like this by default:
```
commands
- fun
> cat.js
> ...
- general
> help.js
> ping.js
> ...
- image-editing
> caption.js
> speed.js
> ...
```
As you can see, each command is grouped into categories, which are represented by subdirectories. To create a new category, you can simply create a new directory inside of the `commands` directory, and to create a new command, you can create a new JS file under one of those subdirectories.
## Commnand Structure
It's recommended to use the `Command` class located in `classes/command.js` to create a new command in most cases. This class provides various parameters and fields that will likely be useful when creating a command. Here is a simple example of a working command file:
```js
import Command from "../../classes/command.js";
class HelloCommand extends Command {
async run() {
return "Hello world!";
}
static description = "A simple command example";
static aliases = ["helloworld"];
}
export default HelloCommand;
```
As you can see, the first thing we do is import the Command class. We then create a new class for the command that extends that class to provide the needed parameters. We then define the command function, which is named `run`. Some static parameters, including the command description and an alias for the command, `helloworld`, are also defined. Finally, once everything in the command class is defined, we export the new class to be loaded as a module by the command handler.
The default command name is the same as the filename that you save it as, excluding the `.js` file extension. If you ever want to change the name of the command, just rename the file.
The parameters available to your command consist of the following:
- `this.client`: An instance of an Eris `Client`, useful for getting info or performing lower-level communication with the Discord API. Documentation for this type can be found [here](https://abal.moe/Eris/docs/Client).
- `this.cluster`: The ID of the eris-fleet cluster that the command is being run from. This should be a number greater than or equal to 0.
- `this.worker`: The ID of the current eris-fleet worker. This should be a number greater than or equal to 0.
- `this.ipc`: An eris-fleet `IPC` instance, useful for communication between worker processes. Documentation for this type can be found [here](https://danclay.github.io/eris-fleet/classes/IPC.html).
- `this.message`: An Eris `Message` object of the message that the command was run from, useful for interaction and getting info about the channel/server that the command was run in. Documentation for this type can be found [here](https://abal.moe/Eris/docs/Message).
- `this.args`: An array of text arguments passed to the command.
- `this.content`: A string of the raw content of the command message, excluding the prefix and command name.
- `this.specialArgs`: An object of special arguments (e.g. `--argument=true`) passed to the command. These arguments are stored in a key/value format, so following the previous example, `this.specialArgs.argument` would return true.
- `this.reference`: An object that's useful if you ever decide to reply to a user inside the command. You can use [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) to combine your message content with this parameter.
Some static fields are also available and can be set depending on your command. These fields are listed below:
- `description`: Your command's description, which is shown in the help command.
- `aliases`: An array of command aliases. People will be able to run the command using these as well as the normal command name.
- `arguments`: An array of command argument types, which are shown in the help command.
- `flags`: An array of objects specifying command flags, or special arguments, that will be shown when running `help <command>` Example:
```js
static flags = [{
name: "argument",
description: "Does a thing"
}];
```
## The `run` Function
The main JS code of your command is specified in the `run` function. This function should return a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) of your command output, which is why the `run` function [is an async function by default](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function). The return value inside the `Promise` should be either a string or an object; you should return a string whenever you intend to reply with plain text, or an object if you intend to reply with something else, such as an embed or attachment.

26
docs/docker.md Normal file
View file

@ -0,0 +1,26 @@
# Docker
You can run the bot as well as its dependencies as a series of Docker containers. However, the manual setup is still recommended if you want more control over the bot.
To start, install Docker on your system via the instructions here: https://docs.docker.com/engine/install/#server
Once you've installed Docker, you should clone the esmBot repo:
```sh
cd ~
git clone --recurse-submodules https://github.com/esmBot/esmBot
cd esmBot
```
Modify the `.env` file as described in step 5 of the manual setup. Make sure to change the `DB` option to this, however:
```
DB=postgresql://esmbot:verycoolpass100@postgres:5432/esmbot
```
You should then modify the `servers.json` file to change the IP addresses of the servers to match the Docker containers. Example:
```json
{
"lava": [
{ "name": "localhost", "url": "localhost:2333", "auth": "youshallnotpass", "local": true }
],
"image": [
{ "server": "api", "auth": "verycoolpass100", "tls": false }
]
}
```
Finally, start the bot by running `docker-compose up -d`.

63
docs/postgresql.md Normal file
View file

@ -0,0 +1,63 @@
# PostgreSQL
Here are some instructions for setting up PostgreSQL for use with esmBot.
**1. Install PostgreSQL.**
#### Alpine
```sh
sudo apk add postgresql
```
#### Debian/Ubuntu
```sh
sudo apt-get install postgresql postgresql-client
```
#### Arch/Manjaro
```sh
sudo pacman -S postgresql
```
***
**2. (Optional) Tune PostgreSQL.**
[PGTune](https://pgtune.leopard.in.ua/) is a useful tool for generating configuration files for your PostgreSQL database. It is highly recommended that you generate a config using this tool as it can increase stability and performance.
***
**3. Create the bot user and database.**
When you install PostgreSQL, it'll create a new user on your system that acts as the "superuser" of the database. You'll need to run Postgres commands as this user; however, you can run a command as that user without switching to it by using `sudo`.
First, you'll need to create a user that the bot can interact with as well as the database itself:
```sh
sudo su - postgres -c "createuser esmbot"
sudo su - postgres -c "createdb esmbot"
```
Then, launch the PostgreSQL shell for the next few commands:
```sh
sudo -u postgres psql
```
If you want to give the user a password, you can do so like this:
```sql
ALTER USER esmbot WITH PASSWORD 'new_password';
```
Once you're inside the shell, you'll need to make sure the bot owns the database and has permissions:
```sql
ALTER DATABASE esmbot OWNER TO esmbot;
```
The database is now accessible by the bot, but it still doesn't know how to add/get data from it. To fix that, you'll need to add some tables. Luckily, the bot comes with a script to automate this:
```sh
POSTGRES_USER=esmbot POSTGRES_DB=esmbot utils/psqlinit.sh
```
You're done!
### Troubleshooting
If you get an error like `error: permission denied for table counts` when attempting to run the bot, try running these commands in the PostgreSQL shell:
```sql
\c esmbot
GRANT ALL PRIVILEGES ON guilds TO esmbot;
GRANT ALL PRIVILEGES ON counts TO esmbot;
GRANT ALL PRIVILEGES ON tags TO esmbot;
\q
```

205
docs/setup.md Normal file
View file

@ -0,0 +1,205 @@
# Setup
Here are some instructions to get esmBot up and running from source.
Recommended system requirements:
- 64-bit CPU/operating system
- Quad-core CPU or better
- 1GB or more of RAM
- Linux-based operating system or virtual machine (Ubuntu 22.04 LTS is recommended)
If you want to run the bot on Windows, [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) is recommended. This guide is somewhat Linux-centric, so for now you're mostly on your own if you decide not to use WSL.
If you have any further questions regarding setup, feel free to ask in the #self-hosting channel on the [esmBot Support server](https://projectlounge.pw/support).
## Setup
#### 1. Install the required native dependencies.
**Debian (bookworm)/Ubuntu (22.04 or later)**
```sh
sudo apt-get install git curl build-essential cmake ffmpeg sqlite3 ttf-mscorefonts-installer libmagick++-dev libvips-dev libcgif-dev libgirepository1.0-dev fonts-noto-color-emoji python3-pip libimagequant-dev
```
**Alpine**
```sh
doas apk add git curl msttcorefonts-installer python3 sqlite3 alpine-sdk cmake ffmpeg imagemagick-dev vips-dev font-noto-emoji py3-pip gobject-introspection-dev cgif-dev libimagequant-dev
```
**Arch/Manjaro**
```sh
sudo pacman -S git curl cmake pango ffmpeg npm imagemagick libvips sqlite3 libltdl noto-fonts-emoji python-pip gobject-introspection libcgif libimagequant
```
Arch/Manjaro users: you'll also need to install [`ttf-ms-fonts`](https://aur.archlinux.org/packages/ttf-ms-fonts/) from the AUR.
***
#### 2. Install libvips.
[libvips](https://github.com/libvips/libvips) is the core of esmBot's image processing commands. The latest version as of writing this (8.12.2) is recommended because it contains fixes to GIF handling; however, there's also a missing feature in this version that is needed for the freeze command to work (see [libvips pull request #2709](https://github.com/libvips/libvips/pull/2709)). To fix this, you'll need to build libvips from source.
Start by installing the Meson build system:
```sh
pip install meson
```
Then, download the source and move into it:
```sh
git clone https://github.com/libvips/libvips
cd libvips
```
From here, you can set up the build:
```sh
meson setup --prefix=/usr --buildtype=release -Dnsgif=true build
```
If that command finishes with no errors, you can compile and install it:
```sh
cd build
meson compile
meson install
```
***
#### 3. Install Node.js.
Node.js is the runtime that esmBot is built on top of. The bot requires version 15 or above to run.
First things first, we'll need to install pnpm, the package manager used by the bot. Run the following to install it:
```sh
curl -fsSL https://get.pnpm.io/install.sh | sh -
```
Once you've done that, continue with the instructions for your operating system below.
**Debian/Ubuntu**
You'll need a more recent version than what's provided in most Debian/Ubuntu-based distros. You can add a repository that contains a supported version by running this command:
```sh
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo bash -
```
After that, you can install Node.js with this command:
```sh
sudo apt-get install nodejs
```
**Alpine**
```sh
doas apk add nodejs
```
**Arch/Manjaro**
```sh
sudo pacman -S nodejs
```
***
#### 4. Set up the database.
esmBot officially supports two database systems: SQLite and PostgreSQL. While SQLite is smaller and requires no initial setup, PostgreSQL has better performance (especially in large environments).
If you would like to use the SQLite database, no configuration is needed and you can move on to the next step.
If you would like to use the PostgreSQL database, view the setup instructions [here](https://github.com/esmBot/esmBot/wiki/PostgreSQL) and come back here when you're finished.
***
#### 5. Clone the repo and install the required Node modules.
```sh
cd ~
git clone --recurse-submodules https://github.com/esmBot/esmBot
cd esmBot
pnpm install
```
You'll also need to copy over some fonts for the image commands:
```sh
sudo cp assets/*.ttf assets/*.otf /usr/local/share/fonts
fc-cache -fv
```
***
#### 6. (Optional) Set up Lavalink.
Lavalink is the audio server used by esmBot for soundboard commands and music playback. If you do not plan on using these features, you can safely skip this step.
Lavalink requires a Java (11 or 13) installation. You can use [SDKMAN](https://sdkman.io) to install Eclipse Temurin, a popular Java distribution:
```sh
sdk install java 11.0.15-tem
```
Initial setup is like this:
```sh
cd ~
mkdir Lavalink
cd Lavalink
wget https://github.com/Cog-Creators/Lavalink-Jars/releases/latest/download/Lavalink.jar
cp ~/esmBot/application.yml .
ln -s ~/esmBot/assets assets
```
To run Lavalink, you can use this command:
```sh
java -Djdk.tls.client.protocols=TLSv1.2 -jar Lavalink.jar
```
***
#### 7. Configure the bot.
Configuration is done via environment variables which can be specified through a `.env` file. Copy `.env.example` to get a starter config file:
```sh
cp .env.example .env
```
If you can't see either of these files, don't worry - Linux treats files whose names start with a . as hidden files. To edit this file in the terminal, run this command:
```sh
nano .env
```
This will launch a text editor with the file ready to go. Create a Discord application at https://discord.com/developers/applications and select the Bot tab on the left, then create a bot user. Once you've done this, copy the token it gives you and put it in the `TOKEN` variable.
When you're finished editing the file, press Ctrl + X, then Y and Enter.
An overview of each of the variables in the `.env` file can be found [here](https://github.com/esmBot/esmBot/wiki/Config).
***
#### 8. Run the bot.
Once everything else is set up, you can start the bot like so:
```sh
pnpm start
```
If the bot starts successfully, you're done! You can invite the bot to your server by generating an invite link [here](https://discordapi.com/permissions.html#3533888).
If you want the bot to run 24/7, you can use the [PM2](https://pm2.keymetrics.io) process manager. Install it using the following command:
```sh
pnpm add -g pm2
```
Once you've done that, you can start the bot using the following command:
```sh
pm2 start app.js
```
***
If you wish to update the bot to the latest version/commit at any time, just run `git pull` and `pnpm install`.
***
## Troubleshooting
### Error: Cannot find module './build/Release/image.node'
The native image functions haven't been built. Run `pnpm run build` to build them.
### Error: connect ECONNREFUSED 127.0.0.1:5432
PostgreSQL isn't running, you should be able to start it with `sudo systemctl start postgresql`. If you don't intend to use PostgreSQL, you should take another look at your `DB` variable in the .env file.
### Gifs from Tenor result in a "no decode delegate for this image format" or "improper image header" error
Tenor GIFs are actually stored as MP4s, which libvips can't decode most of the time. You'll need to get a Tenor API key from [here](https://developers.google.com/tenor/guides/quickstart) and put it in the `TENOR` variable in .env.
### Emojis are missing in some commands
Your system doesn't have an emoji font installed. You can install Google's emoji set with `sudo apt-get install fonts-noto-color-emoji` on Debian/Ubuntu systems, `doas apk add font-noto-emoji` on Alpine, and `sudo pacman -S noto-fonts-emoji` on Arch/Manjaro.
If you want to use the same set that Discord and the main bot uses (Twemoji) then it's slightly more difficult. Go to https://koji.fedoraproject.org/koji/packageinfo?packageID=26306 and choose the latest build, then download the `noarch` RPM file. You'll then have to extract this file; most graphical tools (e.g. 7-Zip, Ark, The Unarchiver) should be able to extract this just fine, but on the command line you'll have to use the `rpm2cpio` tool. The font file should be inside the archive at `usr/share/fonts/Twemoji/Twemoji.ttf`; copy this to `/usr/share/fonts/Twemoji.ttf` (note the / at the beginning). After this, run `fc-cache -fv` and you should be good to go!
### Sound/music commands do nothing
Make sure Lavalink is running and started up completely. The bot skips loading sound commands if Lavalink is not present, so make sure it's running when the bot starts as well.
***
If you have any further questions regarding self-hosting, feel free to ask in the #self-hosting channel on the [esmBot Support server](https://projectlounge.pw/support).