On Sun, Oct 22, 2017, at 01:28 PM, Marvin Gülker wrote:
Hi,
Am 22. October 2017 um 11:47 Uhr -0700 schrieb Abhilash Raj <maxking@asynchronous.in>:
As Simon mentioned, try using DEBUG=False, if you don't already have that. With DEBUG=True, you should see emails printed in a
emailsdirectory undermailman-suite_projectdirectory.Bingo! Man, I was not seeing the forest for the trees. I should have peeked inside that emails folder. And yes, changing the DEBUG flag resolves the problem and emails now go out as they should. My bad! Thank you!
That being said, the enormous number of configuration files to consider and dozens of cross-references to other pages in the docs make the installation guide hard to follow; it also lacks logical structure in my opinion, when it refers to parts of the configuration which are later explained. For someone like me who never programmed a Django application (Ruby dev) this is all pretty cryptic. Especially, that some parts of information are on <http://docs.list.org/en/latest/index.html> whereas other parts are scattered over readthedocs.io makes it very complicated.
There are only two primary configuration files (there are a few more for finer configurations ;-):
Mh, mailman.cfg, settings.py, and hyperkitty.py are three. But I agree, I exaggerated.
All the settings mentioned in the documentation go to either of these files, except, when configuring web server and mail server. Please open an issue[2] if it is not clear where a particular configuration snippet goes and we will fix it.
I'll open an issue later; for now off the top of my head so I won't forget I came over these problems with the docs:
- The linked installation guide for Sass (<http://sass-lang.com/install>) does not include any C/C++ implementation you speak of.
Fixed, http://sass-lang.com/libsass is the correct URL, not sure why is
it not mentioned under /install.
- The mailman-suite's settings.py includes a handler for Less, which is not mentioned in any documentation.
I don't think we use less anymore, I will confirm this and remove it
if needed. It hasn't caused a problem yet, so I am assuming it is never
used.
https://gitlab.com/mailman/mailman-suite/issues/7
- It's officially suggested to use the "fhs" filesystem path layout. It's not documented that you need to create the exact directories and change permissions accordingly; even worse, if one uses this layout, Mailman tries to write into /sbin, which only the package manager is allowed to do. Thus, don't recommend that layout in <http://docs.list.org/en/latest/config-core.html>.
I have been thinking which layout is best and should be used. FHS makes
most sense, but it is true that pip can't write to /sbin and hence
it doesn't work if you aren't using a package manager.
I have changed the docs to recommend master layout which uses the
whichever directory the mailman command is stored in as bin_dir.
- This page: <http://docs.list.org/en/latest/config-core.html> does not mention that the "postfix_lmtp" and "postfix_domains" files are *generated* by Mailman. I spend quite some time looking for these files before I found in the Mailman Core docs that they're generated and it was not an error in my installation.
Added a note about it in the docs under "Configuring MTA" section.
- This page: <http://docs.list.org/en/latest/config-core.html> configures the LMTP server and the REST API server for the same TCP port (8024). This clashes.
Fixed, thanks!
- This page: <http://docs.list.org/en/latest/config-web.html> should mention the thing with the DEBUG variable we've successfully worked through in this thread.
Added a note about it.
- There's no mention of how to create the initial superuser on <http://docs.list.org/en/latest/>, it is hidden down in <https://postorius.readthedocs.io/en/latest/setup.html>, where however there's no mention of the mailman-suite, but some kind of "example_project". It was unclear to me whether this now applied to me or not.
Added a section about it under http://docs.mailman3.org/en/latest/config-web.html
- <http://docs.list.org/en/latest> contains quite some pip install commands (duplicated from the postorius/hyperkitty/core docs), but it's missing "$ pip3 install mailman-hyperkitty", which is only mentioned in <http://hyperkitty.readthedocs.io/en/latest/install.html> in the text body (but not as a command block).
Added to the installation guide.
- This page: <http://mailman.readthedocs.io/en/latest/src/mailman/docs/mta.html> uses "configuration: python:mailman.config.postfix" in the introductory text without explanation, but down in the Postfix-specific block the directive is missing with no explanation. I opted to include it, but I don't know whether that's now correct or not.
You only need to specify settings that you want to override from default. "configuration" for Postfix used to be completely blank until recently, when we added support for regex maps along with hash maps in Postfix. The default is set to hash maps and you don't need to specify the configuration if you using it, if you need to use regex maps, you create a new configuration file and point to it under "configuration".
I will see how to make that more clear in there.
The overall problem I had with the docs is that they can't be followed top-down. One has to refer to the subproject docs if something is unclear, then searching in them until one finds what one was looking for (even if one doesn't know what one is looking for, as with the superuser creation command). I totally appreciate the detailed subproject-docs approach, but you should follow it consequently then. That is, do not duplicate some information from the subproject docs in the mailman-suite docs. It creates the impression as if the mailman-suite docs are complete, which they aren't. Instead, the mailman-suite docs should use explicit references, for example:
- Do this...
- Now follow the procedure outlined in [Postorius Installation link]
- Do something else...
- Follow the procudedure in [Hyperkitty installation link]
That way, the Mailman installation guide would be less of a puzzle. It however might just be me. I apologise if I sound silly.
It wasn't silly at all, in-fact you comments were very helpful to improve the documentation. We would like to not make assumptions about pre-requisite knowledge to use Mailman's documentation and it is hard for us developers to do that without feedback.
Thanks a lot to you!
-- Abhilash Raj maxking@asynchronous.in