ricariel/rspamd repository overview

⁠rspamd-docker

A production-ready Rspamd⁠ container image built on the official rspamd/rspamd image, with an opinionated default configuration, runtime env-var wiring, and optional integration with a range of external spam-fighting services.

The container runs as the unprivileged user 11333 (_rspamd).

⁠Table of Contents

• Ports⁠
• Quick Start⁠
• Scoring & Detection⁠
  • Action Thresholds⁠
  • Blocklists (RBLs)⁠
  • Active Detection Modules⁠
• Environment Variables⁠
  • Core⁠
  • External Services⁠
  • Dynamic Rule Feeds⁠
  • DMARC Aggregate Reporting⁠
• Custom Configuration (/data)⁠
• DKIM Signing⁠
• ARC Signing & Verification⁠
• Fuzzy Hashing⁠
• Multimap Rules⁠
• Docker Compose Example⁠
• Building from Source⁠

⁠Ports

⁠Quick Start

docker run -d \
  --name rspamd \
  -p 11332:11332 \
  -p 11333:11333 \
  -p 11334:11334 \
  -e REDIS=redis:6379 \
  -e RSPAMD_PASS=changeme \
  ricariel/rspamd

The generated web-UI password is printed to stdout on first start (when no worker-controller.inc exists yet). Open http://<host>:11334 to access the dashboard.

⁠Scoring & Detection

⁠Action Thresholds

The following thresholds are baked into the image (conf/local.d/actions.conf):

No single signal should reach 15 on its own (except explicit hard-blocks like country blocks or filename blocks). The design goal is 2 to 3 moderate hits combining to cross the threshold.

⁠Blocklists (RBLs)

Default-module RBLs — handled by Rspamd's built-in rbl module, scored via conf/local.d/rbl_group.conf using the module's own symbol names:

Custom RBLs — defined in conf/local.d/rbl.conf, scored in conf/local.d/rbl_group.conf:

Optional: mount /data/local.d/custom/dqs-rbl.conf to enable the paid Spamhaus DQS feed.

⁠Active Detection Modules

Beyond RBLs, the image enables and configures several additional Rspamd modules:

Notable composite rules (composites.conf):

⁠Environment Variables

All variables are optional unless marked required. The entrypoint re-generates affected config files from scratch on every container start, so every restart is fully idempotent.

⁠Core

CONTROLIP, DNSSEC and NOGREY are printed by the entrypoint at startup but are not wired to any configuration. Setting them has no effect. Disable greylisting through a mounted /data/local.d/greylist.conf instead.

⁠External Services

Each service runs as a separate sidecar container. Set the variable to the container's hostname (the port is fixed per service).

⁠Dynamic Rule Feeds

All feeds are handled by a single background process, update_daemon.sh, started by the entrypoint when at least one feed is enabled. It runs every enabled feed once at startup and then every 12 hours.

Each feed compares the remote ETag against the one stored from the last successful download and skips the transfer when nothing changed, so the interval costs a HEAD request per feed rather than a full download.

⁠DMARC Aggregate Reporting

When DMARC_DOMAIN is set, Rspamd collects DMARC statistics (requires REDIS) and sends daily aggregate reports to domain owners whose mail you process.

Reports are sent once per day (send_interval = 1d) with up to 1000 entries per report. The dmarc.conf is regenerated from scratch on every container start, so changing these variables takes effect on the next restart.

⁠Custom Configuration (/data)

Mount a directory to /data to inject or override any configuration file without rebuilding the image. The entrypoint symlinks files into the correct Rspamd config directories at startup.

/data/
├── local.d/          → /etc/rspamd/local.d/   (merged with built-in config)
│   ├── arc.conf      # override ARC signing key/selector
│   ├── dkim/         # DKIM private keys (see DKIM Signing)
│   └── maps.d/       # writable map files (greylist, bayes, etc.)
├── override.d/       → /etc/rspamd/override.d/ (replaces built-in config)
└── plugins.d/        → /etc/rspamd/plugins.d/

Files in /data/local.d/ that already exist in the built-in config are replaced (the original is removed and a symlink is created). A warning is printed to stdout for each replaced file.

Special handling:

• /data/local.d/rspamd.conf.local → linked as /etc/rspamd/rspamd.conf.local
• /data/local.d/dkim/ → linked as /etc/rspamd/local.d/dkim/
• /data/local.d/maps.d/ → replaces the built-in maps.d/ directory

⁠DKIM Signing

Place your private key(s) in /data/local.d/dkim/ and create a /data/local.d/dkim_signing.conf:

# /data/local.d/dkim_signing.conf
domain {
  example.com {
    path = "/etc/rspamd/local.d/dkim/example.com.key";
    selector = "2024010101";
  }
}

The key file must be readable by the _rspamd user inside the container.

⁠ARC Signing & Verification

Verification is enabled in the base image by default — Rspamd validates incoming ARC chains and can trust forwarded mail (e.g. from mailing lists) even when SPF/DKIM fail for the forwarded copy.

Signing is disabled in the base image (no keys present). To enable it, mount an arc.conf via /data/local.d/arc.conf:

# /data/local.d/arc.conf
enabled = true;
sign_inbound = true;
allow_envfrom_empty = true;
allow_hdrfrom_mismatch = true;
allow_username_mismatch = true;
path = "/etc/rspamd/local.d/$selector.key";
selector = "20250101001";
try_fallback = true;
use_redis = false;

The key file referenced by path must also be mounted into the container.

⁠Fuzzy Hashing

The fuzzy storage combines two sources:

• Public (fuzzy.rspamd.com:11335) — Rspamd's community hash database
• Local (127.0.0.1:11335) — your own private fuzzy storage

Three local flags are pre-configured:

The spamtrap (spamtrap.conf) automatically learns incoming mail to addresses listed in /var/lib/rspamd/spamtrap.map into flag 11.

⁠Multimap Rules

The image ships a large set of multimap rules covering German- and English-language spam categories. Rules are split by language and topic:

Maps are stored under conf/local.d/maps.d/. To add your own entries, mount a writable maps.d/ directory via /data/local.d/maps.d/.

The rule set in the image comes from martinschaible/rspamd-rules⁠, downloaded during the build. Do not edit the _multimap_*.conf files in this repository to add your own rules — a rebuild replaces them. Put local additions into mm_fabrice.conf, which multimap.conf includes and the build leaves alone.

⁠Docker Compose Example

services:
  rspamd:
    image: ricariel/rspamd:latest
    restart: unless-stopped
    ports:
      - "11332:11332"   # milter
      - "11333:11333"   # scanner
      - "11334:11334"   # web UI
    environment:
      REDIS: redis:6379
      RSPAMD_PASS: "changeme"
      CLAMAV: clamav
      OLEFY: olefy
      RAZORFY: razorfy
      PYZOR: pyzor
      BAZAAR: "1"
      HEINLEIN: "1"
      KAM: "1"
      DMARC_DOMAIN: "example.com"
      DMARC_SMTP: postfix
      WAITFOR: "tcp://redis:6379 tcp://clamav:3310"
    volumes:
      - /data/rspamd:/data    # custom config + DKIM keys

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data

  clamav:
    image: clamav/clamav:stable
    restart: unless-stopped

  olefy:
    image: ghcr.io/heinleincloud/olefy:latest
    restart: unless-stopped

  razorfy:
    image: ghcr.io/heinleincloud/razorfy:latest
    restart: unless-stopped

  pyzor:
    image: ghcr.io/heinleincloud/pyzor:latest   # community image
    restart: unless-stopped

volumes:
  redis-data:

⁠Minimal setup (no external services)

services:
  rspamd:
    image: ricariel/rspamd:latest
    restart: unless-stopped
    ports:
      - "11333:11333"
      - "11334:11334"
    environment:
      REDIS: redis:6379
    volumes:
      - /data/rspamd:/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped

⁠Building from Source

git clone https://git.zyria.de/pyrox/rspamd-docker
cd rspamd-docker
docker build -t rspamd-local .

⁠Image contents

The Rspamd version is pinned in the FROM line and raised by Renovate, so a rebuild does not silently change the Rspamd version.

The build overlays the upstream multimap rules on top of the bundled snapshot. If the download fails — an air-gapped build, or --network=none — the build still succeeds and the bundled snapshot is used. The log line says which of the two happened.

⁠Docker Hub

docker pull ricariel/rspamd

https://hub.docker.com/r/ricariel/rspamd⁠