I don't know where the 'read the docs' source code is located at, but given the below forwarded message at the bottom of *this* message, it is my suggestion that the team **strongly modify** the Installation Instructions documentation. [1]
I would suggest that the layout be as follows (adjust formatting accordingly to the spec for writing the documentation):
# Installation Instructions
Depending on your setup and experience administering a machine, you may use one of the following installation methods.
**Note that for a production setup it is STRONGLY recommended you use the pip / virtualenv installation option, as it is most widely supported and less likely to have issues introduced by containerization or distribution-specific packages.**
- Virtualenv Installation **(most recommended for Production instances)** - Installing Mailman using Debian distro packages - Mailman 3 in Docker Containers
This way, the "Most recommended installation method" is listed *first*, and we have a notice made on the installation pages that effectively says "Linux distribution packages and Containerized Mailman3 environments may have changes that diverge from the standard pip/virtualenv solution, and may have bugs related to the ways they're packaged that do not apply to the standard recommended installation method."
This was inspired becuase of the MM3-users message that I included in my 'forwarded' section below - in many cases, the "upstream software" doesn't watch / maintain the Debian or distro-specific issues, and thus is not capable of providing the insight necessary to actually do anything to assist with those issues - calling them "Distro-specific" and then saying "Upstream can't help you".
Thomas
-------- Forwarded Message -------- Subject: [MM3-users] Debian bug report Date: Tue, 03 Mar 2026 16:08:52 -0500 From: Paul Tomblin via Mailman-users <mailman-users@mailman3.org> Reply-To: Paul Tomblin <ptomblin@xcski.com> To: mailman-users@mailman3.org
So I went to submit a bug report to Debian about the fact that the mailman3-web page drags in nginx for no reason. Turns out that the bug had been reported in 2021 and nobody who worked on it who understood mailman understood apache and nobody who worked on it who understood apache understood mailman[1]. So I submitted an update.
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1002795
[1] Literally, one of the developers said Thanks, I admit initially I had no plan on supporting apache2 as I don't use it. Jonas did that part and therefore I did not follow at all.
Paul Tomblin
Mailman-users mailing list -- mailman-users@mailman3.org To unsubscribe send an email to mailman-users-leave@mailman3.org https://lists.mailman3.org/mailman3/lists/mailman-users.mailman3.org/ Archived at: https://lists.mailman3.org/archives/list/mailman-users@mailman3.org/message/...
This message sent to teward@thomas-ward.net