Improve documentation around bot setup

Adding comments and suitable defaults to the .env files

.env.example

@@ -1 +1,2 @@
-KEY=32_character_encryption_key
+# Random 32 character key to encrypt with
+KEY="abcdefghijlmnopqrstuvwxyz1234567"

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 <https://zeppelin.gg/> 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
+👉 **No support is guaranteed for self-hosting 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
 
-### Running the API server
+### Running the backend
-1. `cd backend`
+
-2. `npm ci`
+1. Go into the backend directory: `cd backend`
-3. Make a copy of `api.env.example` called `api.env`, fill in the values
+
-4. Run the desired start script:
+2. Install dependencies: `npm ci`
-    * `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
+3. Make a copy of `bot.env.example` and `api.env.example` (removing the `.example` suffix), fill in the values.
-    * `npm run watch` to watch files and run the **bot and api both** in a **development** environment
+  There are defaults for your convenience, feel free to replace these.
-      with automatic restart on file changes
+
+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`
+1. Go into the dashboard directory: `cd dashboard`
-3. Make a copy of `.env.example` called `.env`, fill in the values
+
+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 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 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: '!'

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=
+# The callback url from the Oauth2 flow, needs to be added as a redirect
-DASHBOARD_URL=
+OAUTH_CALLBACK_URL="http://localhost:8800/auth/oauth-callback"
-DB_HOST=
+# 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"]

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=

dashboard/.env.example

@@ -1 +1,2 @@
-API_URL=
+# URL to the API server running with the bot
+API_URL="http://localhost:8800"