From c9fa56de2c77beaf59b88b1f89a97fb15368708a Mon Sep 17 00:00:00 2001 From: Bluenix Date: Mon, 14 Jun 2021 00:16:24 +0200 Subject: [PATCH] Improve documentation around bot setup Adding comments and suitable defaults to the .env files --- .env.example | 3 +- README.md | 84 ++++++++++++++++++++++++++--------------- backend/api.env.example | 16 +++++--- backend/bot.env.example | 4 +- dashboard/.env.example | 3 +- 5 files changed, 71 insertions(+), 39 deletions(-) diff --git a/.env.example b/.env.example index ab4597a4..61f15027 100644 --- a/.env.example +++ b/.env.example @@ -1 +1,2 @@ -KEY=32_character_encryption_key +# Random 32 character key to encrypt with +KEY="abcdefghijlmnopqrstuvwxyz1234567" diff --git a/README.md b/README.md index 02eae9ee..8572ae0d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ ![Zeppelin Banner](assets/zepbanner.png) + # Zeppelin + Zeppelin is a moderation bot for Discord, designed with large servers and reliability in mind. **Main features include:** + - Extensive automoderator features (automod) - Word filters, spam detection, etc. - Detailed moderator action tracking and notes (cases) @@ -17,52 +20,71 @@ Zeppelin is a moderation bot for Discord, designed with large servers and reliab - Starboard - And more! -See https://zeppelin.gg/ for more details. +See for more details. ## Development -These instructions are intended for bot development only. -👉 **No support is offered for self-hosting the bot!** 👈 +These instructions are intended for bot development only, they are not safe to follow for self-hosting. -### Running the bot -1. `cd backend` -2. `npm ci` -3. Make a copy of `bot.env.example` called `bot.env`, fill in the values -4. Run the desired start script: - * `npm run build` followed by `npm run start-bot-dev` to run the bot in a **development** environment - * `npm run build` followed by `npm run start-bot-prod` to run the bot in a **production** environment - * `npm run watch` to watch files and run the **bot and api both** in a **development** environment - with automatic restart on file changes -5. When testing, make sure you have your test server in the `allowed_guilds` table or the guild's config won't be loaded at all +👉 **No support is guaranteed for self-hosting the bot!** 👈 -### Running the API server -1. `cd backend` -2. `npm ci` -3. Make a copy of `api.env.example` called `api.env`, fill in the values -4. Run the desired start script: - * `npm run build` followed by `npm run start-api-dev` to run the api in a **development** environment - * `npm run build` followed by `npm run start-api-prod` to run the api in a **production** environment - * `npm run watch` to watch files and run the **bot and api both** in a **development** environment - with automatic restart on file changes +### Running the backend + +1. Go into the backend directory: `cd backend` + +2. Install dependencies: `npm ci` + +3. Make a copy of `bot.env.example` and `api.env.example` (removing the `.example` suffix), fill in the values. + There are defaults for your convenience, feel free to replace these. + +4. Setup the database schema, use `npm run migrate-dev`. + +5. Run `npm run build` followed by the desired start script: + - **Recommended** is to use `npm run watch`, this starts both the bot and api server and automatically restarts on save. + - `npm run start-bot-dev` to start the bot. + - `start-api-dev` to start the api server. + +6. On the first run you need to add your guild to the `allowed_guilds` table, otherwise the bot leaves on next restart. + Use the following queries (replacing the all-caps variables): + +```sql +INSERT INTO allowed_guilds (id, name, icon, owner_id) VALUES ("SERVER_ID", "SERVER_NAME", null, "OWNER_ID"); +``` + +```sql +INSERT INTO configs (id, `key`, config, is_active, edited_by) +VALUES (1, "global", "{\"prefix\": \"!\", \"owners\": [\"YOUR_ID\"]}", true, "YOUR_ID"); + +INSERT INTO configs (id, `key`, config, is_active, edited_by) +VALUES (2, "guild-GUILD_ID", "{\"prefix\": \"!\", \"levels\": {\"YOUR_ID\": 100}, \"plugins\": { \"utility\": {}}}", true, "YOUR_ID"); +``` ### Running the dashboard -1. `cd dashboard` -2. `npm ci` -3. Make a copy of `.env.example` called `.env`, fill in the values + +1. Go into the dashboard directory: `cd dashboard` + +2. Install dependencies for the dashboard: `npm ci` + +3. Make a copy of `.env.example` called `.env`, fill in the values. + 4. Run the desired start script: - * `npm run build` compiles the dashboard's static files to `dist/` which can then be served with any web server - * `npm run watch` runs webpack's dev server that automatically reloads on changes + - `npm run build` compiles the dashboard's static files to `dist/` which can then be served with any web server + - `npm run watch` runs webpack's dev server that automatically reloads on save ### Notes -* Since we now use shared paths in `tsconfig.json`, the compiled files in `backend/dist/` have longer paths, e.g. + +- Since we now use shared paths in `tsconfig.json`, the compiled files in `backend/dist/` have longer paths, e.g. `backend/dist/backend/src/index.js` instead of `backend/dist/index.js`. This is because the compiled shared files are placed in `backend/dist/shared`. -* The `backend/register-tsconfig-paths.js` module takes care of registering shared paths from `tsconfig.json` for + +- The `backend/register-tsconfig-paths.js` module takes care of registering shared paths from `tsconfig.json` for `ava` and compiled `.js` files -* To run the tests for the files in the `shared/` directory, you also need to run `npm ci` there + +- To run the tests for the files in the `shared/` directory, you also need to run `npm ci` there ### Config format example -Configuration is stored in the database in the `configs` table + +Configuration is stored in the database in the `configs` table. ```yml prefix: '!' diff --git a/backend/api.env.example b/backend/api.env.example index 87afe866..6a17a4e1 100644 --- a/backend/api.env.example +++ b/backend/api.env.example @@ -1,10 +1,16 @@ -PORT= +# The port that the API server should run on +PORT=8800 +# Credentials of the Discord Application: https://discord.com/developers/applications CLIENT_ID= CLIENT_SECRET= -OAUTH_CALLBACK_URL= -DASHBOARD_URL= -DB_HOST= +# The callback url from the Oauth2 flow, needs to be added as a redirect +OAUTH_CALLBACK_URL="http://localhost:8800/auth/oauth-callback" +# URL back to the dashboard +DASHBOARD_URL="http://localhost:1234" +# MariaDB credentials for use by the API server +DB_HOST="localhost" DB_USER= DB_PASSWORD= DB_DATABASE= -STAFF= +# List of user IDs +STAFF=["123"] diff --git a/backend/bot.env.example b/backend/bot.env.example index 8a2956a3..23333125 100644 --- a/backend/bot.env.example +++ b/backend/bot.env.example @@ -1,5 +1,7 @@ +# Discord bot token found at https://discord.com/developers/applications/ TOKEN= -DB_HOST= +# MariaDB credentials for use by the bot itself +DB_HOST="localhost" DB_USER= DB_PASSWORD= DB_DATABASE= diff --git a/dashboard/.env.example b/dashboard/.env.example index fb6be76e..8bcac4d5 100644 --- a/dashboard/.env.example +++ b/dashboard/.env.example @@ -1 +1,2 @@ -API_URL= +# URL to the API server running with the bot +API_URL="http://localhost:8800"