mirror of
https://github.com/PluralKit/PluralKit.git
synced 2026-02-04 21:16:49 +00:00
67 lines
4.2 KiB
Markdown
67 lines
4.2 KiB
Markdown
# PluralKit development documentation
|
|
|
|
Most of PluralKit's code is written in C#, and is split into 3 projects: `PluralKit.Core` (supporting libraries), `PluralKit.Bot` (the Discord bot), and `PluralKit.API` (ASP.NET webserver with controllers for most API endpoints).
|
|
|
|
There is an ongoing effort to port this code to Rust, and we have a handful of crates already.
|
|
Currently, the main Rust services are:
|
|
- `gateway` - connects to Discord to receive events
|
|
- `api` - handles authentication and rate-limiting for the public API, as well as a couple of private endpoints
|
|
- `scheduled_tasks` - background cron job runner, for statistics and miscellaneous cleanup.
|
|
- `avatars` - handles avatar storage and cleanup
|
|
- `dispatch` - dispatches webhook events
|
|
|
|
Additionally, `libpk` handles runtime configuration and database functions.
|
|
|
|
At the very least, `PluralKit.Bot` and `gateway` are required for the bot to run. While code still exists to connect to the Discord gateway directly from the C# bot, this is no longer a supported configuration and may break in the future.
|
|
|
|
Service-specific documentation can be found for the C# services in [dotnet.md](./dotnet.md), and for the Rust services in [rust.md](./rust.md).
|
|
|
|
## Building/running
|
|
|
|
PluralKit uses a PostgreSQL database and a Redis database to store data. User-provided data is stored in Postgres; Redis is used for internal state and transient data such as the command execution cache. It's generally easy to run these in Docker or with the Nix `process-compose`, but any install method should work.
|
|
|
|
The production instance of PluralKit uses Docker images built in CI. These take a long time to rebuild and aren't good for development (they're production builds, so it's not possible to hook up a debugger). Instead, it's preferable to install build dependencies locally. This is easy with the provided Nix flake: run `nix develop .#bot` to drop into a shell with all the C# build dependencies available, and `nix develop .#services` to get a shell with the Rust build dependencies. It's also okay to manually install build dependencies if you prefer.
|
|
|
|
PluralKit services are configured with environment variables; see service-specific documentation for details. Generally, the configuration from the self-host `docker-compose.yml` should get you started.
|
|
|
|
### process-compose basic steps
|
|
|
|
Your .env should contain at least the following for the bot to run (see the C#/Rust service specific docs for more on configuration):
|
|
```
|
|
pluralkit__discord__bot_token="<YOUR_BOT_TOKEN_HERE>"
|
|
PluralKit__Bot__Token="<YOUR_BOT_TOKEN_HERE>"
|
|
pluralkit__discord__client_id="<YOUR_CLIENT_ID_HERE>"
|
|
PluralKit__Bot__Client="<YOUR_CLIENT_ID_HERE>"
|
|
|
|
RUST_LOG="info"
|
|
pluralkit__db__db_password="postgres"
|
|
pluralkit__db__data_db_uri="postgresql://postgres@localhost:5432/pluralkit"
|
|
pluralkit__db__data_redis_addr="redis://localhost:6379"
|
|
pluralkit__discord__client_secret=1
|
|
pluralkit__discord__max_concurrency=1
|
|
pluralkit__discord__gateway_target="http://localhost:5002/events"
|
|
pluralkit__runtime_config_key=gateway
|
|
PluralKit__Database="Host=localhost;Port=5432;Username=postgres;Password=postgres;Database=pluralkit"
|
|
PluralKit__RedisAddr="localhost:6379"
|
|
PluralKit__Bot__DisableGateway="true"
|
|
PluralKit__Bot__EventAwaiterTarget="http://localhost:5002/events"
|
|
PluralKit__Bot__HttpListenerAddr="127.0.0.1"
|
|
PluralKit__Bot__HttpCacheUrl="localhost:5000"
|
|
```
|
|
|
|
1. Clone the repository: `git clone https://github.com/PluralKit/PluralKit`
|
|
2. Create a `.env` configuration file in the `PluralKit` directory *(see above)*
|
|
3. Build and run: `nix run .#dev`
|
|
- This will download the dependencies, build, and run PluralKit
|
|
- If Nix is not setup to allow flakes, you may need to add `--extra-experimental-features nix-command --extra-experimental-features flakes` to the command
|
|
- If the `pluralkit-bot` process fails to run, you can restart it by selecting it and pressing `Ctrl-R`
|
|
```
|
|
[nix-shell:~]$ git clone https://github.com/PluralKit/PluralKit
|
|
[nix-shell:~]$ cd PluralKit
|
|
[nix-shell:~/PluralKit]$ nano .env
|
|
[nix-shell:~/PluralKit]$ nix run .#dev
|
|
```
|
|
|
|
## Upgrading database from legacy version
|
|
If you have an instance of the Python version of the bot (from the `legacy` branch), you may need to take extra database migration steps.
|
|
For more information, see [LEGACYMIGRATE.md](./LEGACYMIGRATE.md).
|