---
gitea: none
include_toc: true
---

# Draupnir

Draupnir is the way to do moderation. It can exchange banlists with other
servers, and drop reports that people send into its moderation room so that
moderators can act upon them.

Start by creating a room where moderators can give Draupnir commands. This
room should not be encrypted. Then create a user for Draupnir, this user
should ideally be an admin user.

Once you've created the user, log in as this user, maybe set an avatar, join
the room you've created and then copy the access token. This token is used by
the Draupnir software to login.

After that, close the window or client, but
do not logout. If you logout, the token will be invalidated.

Make sure you have the right npm, Node.js, yarn and what-have-you ([see
Draupnir's documentation](https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian))
and prepare the software:

```
mkdir /opt
cd /opt
git clone https://github.com/the-draupnir-project/Draupnir.git
cd Draupnir
git fetch --tags
mkdir datastorage
yarn global add corepack
useradd -m draupnir
chown -R draupnir:draupnir
```

Now, "compile" the stuff as user draupnir:

```
sudo -u draupnir bash -c "install yarn"
sudo -u draupnir bash -c "yarn build"
```

When this is completed successfully, it's time to configure Draupnir.


# Configuration

Under `config` you'll find the default configuration file, `default.yaml`.
Copy it to `production.yaml` and change what you must.

| Option | Value | Meaning |
| :---- | :---- | :---- |
| `homeserverUrl` | `http://localhost:8008` | Where to communicate with Synapse when using network port|
| `homeserverUrl` | `http://unix:/run/matrix-synapse/incoming_main.sock` | Where to communicate with Synapse when using UNIX sockets (see [Workers](../synapse/workers.md)) |
| `rawHomeserverUrl` | `https://matrix.example.com` | Same as `server_name` |
| `accessToken` | access token | Copy from login session or create in [Synapse Admin](../synapse-admin)) |
| `password` | password | Password for the account |
| `dataPath` | `/opt/Draupnir/datastorage` | Storage |
| `managementRoom` | room ID | Room where moderators command Draupnir |

This should give a working bot.

There are a few other bits that you probably want to change. Draupnir can
direct reports to the management room, this is what you should change to
activate that:

```
web:
  enabled: true
  port: 8082
  address: ::1
  abuseReporting:
    enabled: true

pollReports: true
displayReports: true
```

For this to work (for reports to reach Draupnir) you'll need to configure
nginx to forward requests for reports to Draupnir:

```
location ~ ^/_matrix/client/(r0|v3)/rooms/([^/]*)/report/(.*)$ {
    # The r0 endpoint is deprecated but still used by many clients.
    # As of this writing, the v3 endpoint is the up-to-date version.
    
    # Alias the regexps, to ensure that they're not rewritten.
    set $room_id $2;
    set $event_id $3;
    proxy_pass http://[::1]:8082/api/1/report/$room_id/$event_id;
}

# Reports that need to reach Synapse (not sure if this is used)
location /_synapse/admin/v1/event_reports {
    proxy_pass http://localhost:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
    client_max_body_size 50M;
    proxy_http_version 1.1;
    
location ~ ^/_synapse/admin/v1/rooms/([^/]*)/context/(.*)$ {
    set $room_id $2;
    set $event_id $3;
    proxy_pass http://localhost:8008/_synapse/admin/v1/rooms/$room_id/context/$event_id;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
    client_max_body_size 50M;
    proxy_http_version 1.1;
}
```

# Rate limiting

Normal users are rate limited, to prevent them from flooding the server. Draupnir
is meant to stop those events, but if it it itself rate limited, it won't work
all that well.

How rate limiting is configured server-wide is documented in [Synapse's
documentation](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html?highlight=ratelimiting#ratelimiting).
Overriding is, unfortunately, not something you can easily configure in the
configuration files. You'll have to do that in the database itself:

```
INSERT INTO ratelimit_override VALUES ('@draupnir:example.com', 0, 0);
```