### Start Draupnir Appservice Source: https://the-draupnir-project.github.io/draupnir-documentation/appservice Run this command to start the Draupnir appservice. Ensure the volume mounts and configuration file paths are correct. ```bash docker run -v /your/path/to/draupnir-data/:/data/ gnuxie/draupnir appservice -c /data/config/config.appservice.yaml -f /data/config/draupnir-registration.yaml -p $MATRIX_PORT --draupnir-config /data/config/production.yaml ``` -------------------------------- ### Start Draupnir service Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/systemd Manually start the Draupnir service using systemctl. ```bash systemctl start draupnir.service ``` -------------------------------- ### Example Login and Obtain Access Token with cURL Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_draupnir_account An example of the cURL command to log in and obtain an access token, with placeholders replaced by typical values. Ensure you use your actual credentials. ```bash curl -XPOST --json '{ "identifier": { "type": "m.id.user", "user": "draupnir" }, "password": "********", "type": "m.login.password" }' 'https://matrix-client.example.com/_matrix/client/v3/login' ``` -------------------------------- ### Install Node.js 24 and npm via NodeSource Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Sets up Node.js version 24 and npm using NodeSource's repository for convenient installation on Debian. ```bash curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh ``` ```bash bash nodesource_setup.sh ``` ```bash apt update && apt install nodejs -y ``` -------------------------------- ### Install Draupnir Dependencies and Build Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Installs Node.js dependencies and builds the Draupnir project using npm, executed as the 'draupnir' user. ```bash sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && npm ci" ``` ```bash sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && npm run build" ``` -------------------------------- ### Install mx-tester Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Install the mx-tester tool using cargo, which is necessary for setting up local Synapse instances for integration testing. Ensure you have the Rust toolchain and Docker installed beforehand. ```bash cargo install mx-tester ``` -------------------------------- ### Install Debian Packages Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Installs essential packages required for building and running Draupnir on Debian. ```bash apt update && apt install -y ca-certificates curl git sudo ``` -------------------------------- ### Start Local Synapse with mx-tester Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Start a local Synapse container using the image built by `mx-tester build` and the configuration specified in `mx-tester.yml`. This command is used to spin up a development Synapse instance. ```bash mx-tester up ``` -------------------------------- ### Run Manual Test Server Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Start a manual test server for Draupnir, allowing interaction with a local Synapse instance via a Matrix client. Point your client to http://localhost:9999 and join the management room. ```bash npm run -w apps/draupnir test:manual ``` -------------------------------- ### Enable Draupnir service on boot Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/systemd This command tells systemd to start the Draupnir service automatically when the system boots up. ```bash systemctl enable draupnir.service ``` -------------------------------- ### Install Synapse Module Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module Install the Synapse module to your Synapse Python environment using pip. Ensure you are installing from the correct Mjolnir subdirectory. ```bash pip install -e "git+https://github.com/matrix-org/mjolnir.git#egg=mjolnir&subdirectory=synapse_antispam" ``` -------------------------------- ### Build and Run Draupnir from Source (v3.0.0+) Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_selfbuild Clone the repository, install Node.js 24 dependencies with npm, build the project, copy and edit the configuration, and run the bot. Ensure to adjust the data path in the production configuration if not using Docker. ```bash git clone --branch v3.0.0 --depth 1 https://github.com/the-draupnir-project/Draupnir.git cd Draupnir git fetch --tags npm ci npm run build # Copy and edit the config. It *is* recommended to change the data path, # as this is set to `/data` by default for dockerised draupnir. cp config/default.yaml config/production.yaml nano config/production.yaml ./draupnir-entrypoint.sh bot --draupnir-config ./config/production.yaml ``` -------------------------------- ### Build and Run Draupnir from Source (Legacy Versions v2.9.0 and below) Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_selfbuild For older versions, use yarn classic and Node 20. Install dependencies and build using yarn instead of npm. ```bash yarn install yarn build ``` -------------------------------- ### Build Synapse Image with mx-tester Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Build a Synapse Docker image using mx-tester. This command should be run from the Draupnir project root and is a prerequisite for starting a local Synapse instance. ```bash mx-tester build ``` -------------------------------- ### Run Draupnir Docker Container Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_docker Use this command to start the Draupnir container. Ensure you have a configuration file prepared and specify the data directory. The 'bot' argument is required to run Draupnir in bot mode. ```bash docker run --rm -it --name=draupnir -v ./var/lib/draupnir:/data gnuxie/draupnir:latest bot --draupnir-config /data/config/production.yaml ``` -------------------------------- ### Run Integration Tests Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Execute integration tests for the Draupnir application. This command assumes a local Synapse instance is running, typically started with `mx-tester up`. ```bash npm run -w apps/draupnir test:integration ``` -------------------------------- ### Set Draupnir Directory Ownership Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Assigns ownership of the Draupnir installation directory to the 'draupnir' user and group. ```bash chown -R draupnir:draupnir /opt/mod-bot/Draupnir ``` -------------------------------- ### Configure Synapse HTTP Antispam Module Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse-http-antispam Example configuration for the synapse-http-antispam module within Synapse. Ensure 'base_url' points to your Draupnir instance and 'authorization' is a secret token. 'enabled_callbacks' specify which events Draupnir should check, and 'fail_open' settings prevent service degradation if Draupnir is unavailable. ```yaml modules: - module: synapse_http_antispam.HTTPAntispam config: # http://`:/api/1/spam_check` base_url: http://localhost:8080/api/1/spam_check authorization: YOUR_SECRET_TOKEN do_ping: true enabled_callbacks: - user_may_invite - user_may_join_room fail_open: user_may_invite: true user_may_join_room: true ``` -------------------------------- ### Get Homeserver Client-Server Base URL Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_draupnir_account Fetch the client-server base URL for your Matrix homeserver by querying the .well-known endpoint. This is necessary for obtaining an access token using cURL. ```bash curl https://example.com/.well-known/matrix/client ``` -------------------------------- ### Create a New Policy List with `list create` Command Source: https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists If you need a new writeable list, use `!draupnir list create` followed by a shortcode and an alias. This creates a policy room and an alias for sharing. ```bash !draupnir list create my-bans my-bans-bl ``` -------------------------------- ### Create Beta Release Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/releasing-draupnir Use this command to create a pre-release version, such as a beta release. Specify the pre-release identifier if needed. ```bash yarn version --preminor --preid beta ``` -------------------------------- ### Example Draupnir News JSON Structure Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/draupnir-news This is an example of the JSON structure for a Draupnir news item, including Matrix event content with both plain text and HTML formatted bodies. Ensure the news_id is a valid UUID. ```json { "news": [ { "news_id": "cd1881d2-60d0-49ad-9951-321205efa64b", "matrix_event_content": { "msgtype": "m.notice", "body": "#### 📰 Draupnir Assembly: Call for Participation\n\nThe Longhouse Assembly is determining the next direction for the project.\n\nReview the current cycle and cast your vote:\n\n➡️ [Join the Assembly Discussion](https://matrix.to/#/!DtwZFWORUIApKsOVWi:matrix.org?via=matrix.org&via=feline.support&via=asgard.chat)", "format": "org.matrix.custom.html", "formatted_body": "

📰 Draupnir Assembly: Call for Participation

\n

The Longhouse Assembly is determining the next direction for the project.

\n

Review the current cycle and cast your vote:

\n

➡️ Join the Assembly Discussion

\n" } } ] } ``` -------------------------------- ### Set Protection Property Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections Use this command to change a specific setting for a protection. For example, to set `maxPer` to 5 joins. ```bash !draupnir protections config set JoinWaveShortCircuitProtection maxPer 5 ``` -------------------------------- ### Update Data Path in Configuration Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Modifies the production configuration file to set the correct data path for the installed instance. ```bash sed -i 's|dataPath: "/data/storage"|dataPath: "/opt/mod-bot/Draupnir/datastorage"|' /opt/mod-bot/Draupnir/config/production.yaml ``` -------------------------------- ### Allow Homeserver Provisioning Source: https://the-draupnir-project.github.io/draupnir-documentation/appservice Use this command in your control room to allow provisioning for a specific homeserver. Replace MXID_OF_APPSERVICE_HERE with your appservice's MXID and homeserver_to_allow with the target homeserver's domain. ```text /plain MXID_OF_APPSERVICE_HERE allow @*:homeserver_to_allow ``` -------------------------------- ### Generate UUID v4 for News Item Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/draupnir-news Use this command to generate a unique identifier for a news item. Ensure Node.js is installed. ```bash node -e "console.log(crypto.randomUUID())" ``` -------------------------------- ### Set Timescale for Protection Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections Use this command to adjust the time period over which a protection's limits are applied. For example, setting `timescaleMinutes` to 10. ```bash !draupnir protections config set JoinWaveShortCircuitProtection timescaleMinutes 10 ``` -------------------------------- ### Generate Appservice Registration File Source: https://the-draupnir-project.github.io/draupnir-documentation/appservice Use this command to generate the appservice registration file. Ensure the host and port are correctly specified for your homeserver to access the appservice. ```bash docker run --rm -v /your/path/to/draupnir-data:/data gnuxie/draupnir appservice -r -u "http://$HOST:$MATRIX_PORT" -f /data/config/draupnir-registration.yaml ``` -------------------------------- ### Configure Homeserver for Appservice Source: https://the-draupnir-project.github.io/draupnir-documentation/appservice Add the generated `draupnir-registration.yaml` file to your matrix homeserver's configuration to enable the appservice. ```yaml app_service_config_files: - "/data/draupnir-registration.yaml" ``` -------------------------------- ### Docker Compose for Synapse Module Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module Configure your docker-compose.yaml to bind mount the Synapse antispam module directory into the Synapse container. This is necessary for Docker installations. ```yaml version: '3.7' services: synapse: volumes: - //draupnir/synapse_antispam/mjolnir:/usr/local/lib/python3.12/site-packages/mjolnir ``` -------------------------------- ### Allow User Provisioning Source: https://the-draupnir-project.github.io/draupnir-documentation/appservice Use this command in your control room to allow provisioning for a specific user. Replace MXID_OF_APPSERVICE_HERE with your appservice's MXID and MXID_TO_ALLOW with the target user's MXID. ```text /plain MXID_OF_APPSERVICE_HERE allow MXID_TO_ALLOW ``` -------------------------------- ### Stop Local Synapse Container Source: https://the-draupnir-project.github.io/draupnir-documentation/contributing/development-environment Stop and remove the local Synapse container that was started with `mx-tester up`. This command is used to clean up the development environment after testing. ```bash mx-tester down ``` -------------------------------- ### Copy Default Configuration Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Copies the default configuration file to create a production-specific configuration. ```bash cp /opt/mod-bot/Draupnir/config/default.yaml /opt/mod-bot/Draupnir/config/production.yaml ``` -------------------------------- ### View Configured Capability Providers Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections Use this command to see which capability providers are active for a given protection. It lists capabilities, their interfaces, and the currently configured provider. ```bash !draupnir protections show ``` -------------------------------- ### Configure New Joiner Protection Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/new-joiner-protection Append this configuration to your config file under the `protections:` header. Specify the server names from which new users should be banned. Restart the bot for changes to take effect. You can enable/disable this protection without restarting by managing the servers listed here. ```yaml newJoinerProtection: serverNames: - "example.com" ``` -------------------------------- ### Create Draupnir Directory Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Creates the directory structure where the Draupnir repository will be cloned. ```bash mkdir -p /opt/mod-bot ``` -------------------------------- ### Create Draupnir Data Storage Directory Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Creates the directory for Draupnir's persistent data storage. ```bash mkdir -p /opt/mod-bot/Draupnir/datastorage ``` -------------------------------- ### Configure Synapse Module Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module Add the Synapse module configuration to your homeserver.yaml file. Adjust settings like block_invites, block_messages, block_usernames, and ban_lists to suit your needs. ```yaml modules: - module: mjolnir.Module config: # Prevent servers/users in the ban lists from inviting users on this # server to rooms. Default true. block_invites: true # Flag messages sent by servers/users in the ban lists as spam. Currently # this means that spammy messages will appear as empty to users. Default # false. block_messages: false # Remove users from the user directory search by filtering matrix IDs and # display names by the entries in the user ban list. Default false. block_usernames: false # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir, # this list cannot be room aliases or permalinks. This server is expected # to already be joined to the room - Mjolnir will not automatically join # these rooms. ban_lists: - "!roomid:example.org" #message_max_length: # Limit the characters in a message (event body) that a client can send in an event on this server. # By default there is no limit (beyond the the limit the spec enforces on event size). # Uncomment if you want messages to be limited to 510 characters. # threshold: 510 # Limit messages only in certain rooms rooms. # By default all rooms will enforce the limit. # Uncomment if you want messages to only be subject to character limits in certain rooms. # rooms: # - "!vMvyOCeCxHsggkmALd:localhost:9999" # Also hide messages from remote servers that are over the `message_limit`. # By default only events from this server will be limited. # WARNING: Remote users on other servers will still be able to messages over the limit. # Uncomment to enforce the `message_limit` on events from remote servers. # remote_servers: true ``` -------------------------------- ### Edit Production Configuration Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Opens the production configuration file for manual editing. Key parameters like homeserver URLs, accessToken, and managementRoom should be configured here. ```bash nano /opt/mod-bot/Draupnir/config/production.yaml ``` -------------------------------- ### Show Protection Settings Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections Use this command to display an overview of a protection's settings. Copy protection names from `!draupnir protections`. ```bash !draupnir protections show JoinWaveShortCircuitProtection ``` -------------------------------- ### Subscribe to a Policy List with `watch` Command Source: https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists Use the `!draupnir watch` command to subscribe Draupnir to a policy list and apply its policies to your rooms. Recommended for the community moderation spam list. ```bash !draupnir watch #community-moderation-effort-bl:neko.dev ``` -------------------------------- ### Systemd Unit File for Draupnir Docker Container Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/systemd This systemd unit file defines how to run Draupnir as a Docker container. It includes commands for pulling the latest Docker image, cleaning up old containers, running the new container with persistent storage, and stopping the container gracefully. Configure Docker to handle timeouts for container stops. ```systemd [Unit] Description=Draupnir Docker Container After=docker.service Requires=docker.service After=network-online.target Wants=network-online.target [Service] Type=exec # Update Draupnir ExecStartPre=docker image pull gnuxie/draupnir:latest # Clean up any accidentally existing containers ExecStartPre=docker container rm --force draupnir ExecStart=docker container run --rm --pull=never --name=draupnir -v /var/lib/draupnir:/data gnuxie/draupnir:latest bot --draupnir-config /data/config/production.yaml ExecStop=-docker container stop --time=10 draupnir # Let Docker handle timeout instead TimeoutStopSec=infinity Restart=always RestartSec=30 [Install] WantedBy=multi-user.target ``` -------------------------------- ### Systemd Service Configuration for Draupnir Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Provides a systemd service file to manage the Draupnir bot. This includes settings for execution, user, environment, and security restrictions. ```systemd [Unit] Description=Draupnir #After=matrix-synapse.service # You can enable this if your Matrix server is Synapse, otherwise you might want to change it to the service that starts your homeserver. #After=matrix-synapse.target # You can enable this if your Matrix server is Synapse and you have installed workers via the official instructions. [Service] ExecStart=/opt/mod-bot/Draupnir/draupnir-entrypoint.sh bot --draupnir-config /opt/mod-bot/Draupnir/config/production.yaml WorkingDirectory=/opt/mod-bot/Draupnir Restart=always User=draupnir Environment=PATH=/usr/local/bin:/usr/bin:/bin Environment=NODE_ENV=production SyslogIdentifier=draupnir ReadWritePaths=/opt/mod-bot/Draupnir NoNewPrivileges=yes PrivateDevices=yes PrivateTmp=yes ProtectHome=yes ProtectSystem=strict ProtectControlGroups=true RestrictSUIDSGID=true RestrictRealtime=true LockPersonality=true ProtectKernelLogs=true ProtectKernelTunables=true ProtectHostname=true ProtectKernelModules=true PrivateUsers=true ProtectClock=true SystemCallArchitectures=native SystemCallErrorNumber=EPERM SystemCallFilter=@system-service # EnvironmentFile=-/path/to/env/file # Optional: if you want to load environment variables from a file. [Install] WantedBy=multi-user.target ``` -------------------------------- ### Configure Draupnir Web Server for Abuse Reports Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/homeserver-administration Enable the web server and abuse reporting features in Draupnir's configuration file. Ensure the web server can only receive requests from your reverse proxy (e.g., `localhost`) for security. ```yaml web: enabled: true abuseReporting: enabled: true ``` -------------------------------- ### Issue Compatibility Token with MAS CLI Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_draupnir_account Use this command to issue a compatibility token for Draupnir when using MAS and requiring Synapse admin privileges. This requires an existing account. ```bash mas-cli manage issue-compatibility-token --yes-i-want-to-grant-synapse-admin-privileges ``` ```bash mas-cli manage provision-all-users ``` -------------------------------- ### Add Draupnir User Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Creates a dedicated system user named 'draupnir' to run the bot, avoiding the need for root permissions. ```bash useradd -m draupnir ``` -------------------------------- ### Verify Synapse Module Loaded Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse-http-antispam Check Synapse logs for this message to confirm the synapse-http-antispam module has been successfully loaded. ```log synapse.app._base - 584 - INFO - sentinel - Loaded module ``` -------------------------------- ### Restart Draupnir service Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/systemd Restart the Draupnir service using systemctl. ```bash systemctl restart draupnir.service ``` -------------------------------- ### Fetch Updates and Checkout Version Source: https://the-draupnir-project.github.io/draupnir-documentation/bot/setup_debian Updates the local Draupnir repository by fetching the latest tags from GitHub and checking out a specific version, performed as the 'draupnir' user. ```bash sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && git fetch --tags && git checkout v3.0.0" ``` -------------------------------- ### Restore Default Capability Providers Source: https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections Resets all capability providers for a protection to their default configurations. This command restores the default settings for every capability the protection offers. ```bash !draupnir protections capability reset ```