I have a question for @georglauterbach are the repo commited local.d/ configs copy/paste from the Rspamd package/repo at the time?

For example rspamd/local.d/worker-proxy.inc was committed in Jan 2023:

https://github.com/docker-mailserver/docker-mailserver/blob/v14.0.0/target/rspamd/local.d/worker-proxy.inc

Rspamd was initially introduced with DMS v12 (Debian 11 Bullseye base) released in April 2023 with Rspamd 3.5 (upstream worker-proxy.inc for 3.5) (Debian package would have been 3.4). Looking at the upstream git blame the config added the reject_message line with the other options, so it's unclear why your committed copy differs from upstream by omitting that one.

For our image the equivalent upstream file lives at /etc/rspamd/worker-proxy.inc, with a roughly similar config from us at /etc/rspamd/local.d/worker-proxy.inc to override that:

$ diff /etc/rspamd/worker-proxy.inc /etc/rspamd/local.d/worker-proxy.inc

1,13c1,2
< # Proxy worker setup
< # Please don't modify this file as your changes might be overwritten with
< # the next update.
< #
< # You can modify 'local.d/worker-proxy.inc' to add and merge
< # parameters defined inside this section
< #
< # You can modify 'override.d/worker-proxy.inc' to strictly override all
< # parameters defined inside this section
< #
< # See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
< # for details
< # Module documentation: https://rspamd.com/doc/workers/rspamd_proxy.html
---
> # documentation: https://rspamd.com/doc/workers/rspamd_proxy.html
> # see also: https://rspamd.com/doc/quickstart.html#using-of-milter-protocol-for-rspamd--16
15c4
< milter = yes; # Enable milter mode
---
> bind_socket = "127.0.0.1:11332";
17,23c6,7
< # This timeout is mostly specific to the milter mode.
< # Please also bear in mind that if this timeout is longer than `task_timeout`,
< # your messages might be processed for much longer due to this timeout (this is
< # true for self-scan mode).
< # If this behaviour is not desired, then it is recommended to reduce and adjust this
< # value accordingly
< timeout = 60s;
---
> milter = yes;
> timeout = 120s;
27c11
<   hosts = "localhost";
---
>   self_scan = yes;
30,35c14,18
< count = 1; # Do not spawn too many processes of this type
< max_retries = 5; # How many times master is queried in case of failure
< discard_on_reject = false; # Discard message instead of rejection
< quarantine_on_reject = false; # Tell MTA to quarantine rejected messages
< spam_header = "X-Spam"; # Use the specific spam header
< reject_message = "Spam message rejected"; # Use custom rejection message
---
> count = 2;
> max_retries = 5;
> discard_on_reject = false;
> quarantine_on_reject = false;
> spam_header = "X-Spam";

If possible, I'd like to avoid this becoming an issue over time, similar to the Dovecot config situation. I've largely kept my distance from rspamd in the project but have become a bit more familiar with it lately as we get closer to switching over to it.

I'm a bit iffy about the custom-commands.conf feature, but I hope the revised docs for that in this PR communicate it more clearly. I found the existing docs a bit sporadic to grok and needed to double check by going over your script implementation for it to understand properly. Didn't help that that rspamd docs were another layer of friction, I've better conveyed those insights in the example comments.

I'll do another pass on the page in future when I have more time.

Shifts the config example to switch to Rspamd to the very top of the docs, with the related ENV in a separate section below that. I think that'd be a bit more helpful to the reader for the first time?

Visual diff

Bulk of the changes are covered below, bit easier if you want to compare 😅

Early guidance for how to get going with Rspamd

Before

NOTE: "Other Anti-Spam Services" section seemed a bit redundant with the revision so was removed:

Near the end of the docs page:

After

rspamd/override.d/ + custom-commands.conf

Before

I wasn't a fan of the admonition usage and found these two sections a bit more effort to grok as a new reader to them than I felt they needed to be.

After

Seeing this rendered it could probably be improved a bit, but hopefully it's a step in the right direction 😅

DKIM / ARC sections

Slight improvement here, I'll tackle the unified DKIM feature which will simplify the config further 👍

Before

After

I'm a big fan of admonitions, but the extend to which they are used in our docs leads me to the conclusion that you use them to structure content, instead of using them as additional hints.

Admonitions are similar to GitHub's "Alerts", on which GitHub advises:

Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader.

I agree with this, and hence, I feel like the content on these docs would be better represented without this amount of admonitions.

Would you hence be okay with removing a few admonitions and replacing them with headings again?

I'm a big fan of admonitions, but the extend to which they are used in our docs leads me to the conclusion that you use them to structure content, instead of using them as additional hints.

You are correct, I do over use them while polishing up the docs as personally it makes the content easier to navigate and digest for me than without them.

This concern though is specific to our current docs generator poor typography.

While I would be more familiar with Meta's Docusaurus project due to it's usage of React... I have noticed these two sites docs are using VuePress and I quite like the user experience, both the sidebar for navigation and typography layout. The admonition style less so (see the nushell link for that), but tbh that's probably better since it only further promotes it to be used more minimally 😛

• https://doc.dovecot.org/main/
• https://www.nushell.sh/book/quick_tour.html#acting-on-data

Once the docs have had a full revision pass and been re-organized (I plan to shift pages around by DMS v16), should I have the time I'll look into alternatives to mkdocs-material. I'd prefer to minimize our CSS workarounds for issues upstream won't fix, and better typography/nav would be fantastic too.

Markdown will still be used, non-standard features like admonitions will look a tad different. Admonitions differ in name, for VuePress they're called Custom Containers instead (that is v1, their v2 is in RC stage and seems to be lacking the feature, seems to be moved to a plugin), and they use the same syntax as mkdocs-material plans to migrate to IIRC (we could look into opt-in for that if they're resolved some issues I recall it having last time I investigated).

I don't know if I'm onboard with VuePress itself, but those two references using it at least demonstrate the improvements I'd like our docs to have.

Would you hence be okay with removing a few admonitions and replacing them with headings again?

As mentioned, I'd rather defer that until I've done a full pass over our docs.

No users have been complaining about it so presently it's just a preference/bias difference between us, but we'll be in alignment once content has better structure from improved typography in future 👍

FWIW, regarding admonitions I strongly dislike the use of them as shown in the before screenshots for questions where it wraps the title with no supplementary content. That was done again for an example link.

We have collapsed admonitions which can hide excess related information which is useful for UX, while the other usage you had on this page felt like an anti-pattern to me and conflicted with that UX that implies (at a glance) expandable admonitions 😅

I personally don't see comparisons like the ARC section to be better without admonitions.

Just noticed my custom-commands.conf section has a broken admonition rendered, I'll fix that.

Documentation preview for this PR is ready! 🎉

Built with commit: e6a03a0