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)
Customizable server logs
Tags/custom commands
Reaction roles
Tons of utility commands, including a granular member search
Full configuration via a web dashboard
- Override specific settings and permissions on e.g. a per-user, per-channel, or per-permission-level basis
Bot-managed slowmodes
- Automatically switches between native slowmodes (for 6h or less) and bot-enforced (for longer slowmodes)
Starboard
And more!

See https://zeppelin.gg/ for more details.

Development

These instructions are intended for bot development only, they are not recommended for self-hosting.

👉 No support is offered for self-hosting the bot! 👈

Running the backend

Go into the backend directory: cd backend
Install dependencies: npm ci
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.
Setup the database: npm run migrate-dev
To start the backend, there are two alternatives:
- It is recommended to use npm run watch for development. This will automatically restart on save
- Run npm run build followed by the desired start script:
  - npm run start-bot-dev to start the bot.
  - start-api-dev to start the api server.
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):

INSERT INTO allowed_guilds (id, name, icon, owner_id) VALUES ("SERVER_ID", "SERVER_NAME", null, "OWNER_ID");

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

Go into the dashboard directory: cd dashboard
Install dependencies for the dashboard: npm ci
Make a copy of .env.example called .env, fill in the values.
Run the desired start script:
- npm run watch runs webpack's dev server that automatically reloads on save
- npm run build compiles the dashboard's static files to dist/ which can then be served with any web server

Notes

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 ava and compiled .js files
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.

prefix: '!'

# role id: level
levels:
  "12345678": 100 # Example admin
  "98765432": 50 # Example mod

plugins:
  mod_plugin:
    config:
      kick_message: 'You have been kicked'
      can_kick: false
    overrides:
      - level: '>=50'
        config:
          can_kick: true
      - level: '>=100'
        config:
          kick_message: 'You have been kicked by an admin'

  other_plugin:
    config:
      categories:
        mycategory:
          opt: "something"
        othercategory:
          enabled: false
          opt: "hello"
    overrides:
      - level: '>=50'
        config:
          categories:
            mycategory:
              enabled: false
      - channel: '1234'
        config:
          categories:
            othercategory:
              enabled: true

4.1 KiB Raw Blame History