On Thu, Feb 25, 2021, at 6:38 PM, Brian Carpenter wrote:
On 2/25/21 8:28 PM, Abhilash Raj wrote:
Thanks Brian, this looks quite comprehensive in the details. The only thing I am a bit concerned about is granting sudo privileges to the Mailman user. It really shouldn't have sudo given that Mailman and Django are supposed to run as mailman user. Any compromise of the Django application will provide the attacker root on the machine.
Thanks for pointing that out. I have removed that step. It really wasn't needed.
Great, thanks!
Is there a specific reason that you chose to go with an entirely new doc
Yes. Just from observing the communications on this list, there are multiple ways to install Mailman 3 which produces installation issues, database problems, outdated apps, etc. My document produces a VERY stable installation of Mailman 3 and one that is easy to maintain and update. It is also very comprehensive covering not just Mailman Suite, but the configuration of an entire server environment. Personally I think the choice of Debian, NGINX, Postfix, and PostgreSQL makes for a long and loving relationship with Mailman 3 but I do understand everyone has their own environment that they want to work with. My guide represents a very stable and easily maintained environment for me and hopefully others.
I think it is okay to be pick up a specific configuration and provide a guide to installation keeping that as the target technology. As it happens to be, the official doc uses the same set, Nginx, Postfix and PostgSQL.
https://docs.mailman3.org/en/latest/install/virtualenv.html
I don't see anything very specific to Debian in the doc except the package names and I think they are similar enough in Debian derivative distros that we can write up that assumption up front in the top.
Given that most of the installation is based off on pip, I don't think there is
going to be a *lot* of deviation for even RHEL/Fedora based distros when it
comes to Mailman itself. Some minute deviations could occur with the
behavior of certain commands, like nano doesn't exist, but I still expect
95% of the doc to be the same, except obviously the package names.
rather than helping to improve the existing one? Several parts of it (at least the ones that official guide covers) seems similar to me and is duplicate information that at least two people are going to spend time writing and maintaining in future.
Is there an official guide? See that is the problem. I did not know there was an official guide. Because every time I tried finding documentation in the past using Google searches, I got fed outdated information. So for me the guide that I came up with, works great for me and if no one else uses it, I certainly will.
I am not that well versed in SEO, but the official website https://list.org does point to it. Maybe not prominently enough for new users to discover? I'll see if we can make the discovery of docs.mailman3.org better.
Your guide, by nature has to be minimalistic to accommodate all the various server environments out there. My is meant to be narrow but comprehensive.
I guess it is fine to be opinionated about choosing the technologies but yet provide pointers to help people using other technologies.
Right now, I do that using "Hints" and "Notes" and "See also" banners through out the documentation to point to different pages where they can lookup setup for other technologies. For example, how to setup MySQL if official doc recommends Postgres.
Is it something about the contribution process to the official documentation that makes it hard for people to contribute? Most of the pages at docs.mailman3.org or come from this[1] repo and use Sphinx to build and REsT formatting (.rst).
[1]:https://gitlab.com/mailman/mailman-suite-docWell I don't know much about any of the above approach to documentation. So I would say that is a hindrance.
Gitlab has a fairly good experience editing REsT files and you don't necessarily have to do much outside of a Web Browser actually. It lets you preview before saving like wiki.list.org and you can submit it for review and merging into main repo.
Would you be more willing to contribute to official documentation if we documented the Gitlab contribution process better?
I am just trying to understand how can we lower the barrier for community members to help contribute to existing docs instead of them having to create new ones. Specifically around installation, since that tends to get stale often when depedent packages change or a new dependency is added that breaks the installation.
I had to update my guide twice due to recent changes made to the installation process such as the addition of the Dart Sass section and the problem with the cryptography module when installing Hyperkitty. While my guide covers these new hurdles to a new installation, I don't think yours says anything about them. The Dart Sass section came from Mark's comments on this list.
Because we haven't yet gotten to updating those in the official docs, unfortunately. And there are more things missing like Fulltext search (Xapian recommended) and more of the Email setup like SPF and DKIM. Very much aligned with your plans, which is why I suggested contributing updates to docs.mailman3.org instead :)
-- thanks, Abhilash Raj (maxking)