Update documentation for IMAP, SMTP, LMTP, POP3, ManageSieve, TLS, OIDC#3040
Merged
Conversation
The extendable server is only referenced in very few places and is not included in the navigation. Furthermore, all of its pages include partials that are already included elsewhere and link to the postgres server in most cases. Additionally, all files that produce errors when building the docs are part of the documentation for the extendable server.
…r in own partials This also updates and completely reworks these parts of the documentation. Major corrections include: OIDC: - `oidc.oidcConfigurationURL`: This value is not used. - `oidc.scope`: This value is not used. - Clarify how tokens are validated depending on which config options are provided. Server: - `helloName` sometimes documented as `handler.helloName`. - Value of `helloName` is only used if `autodetect` is explicitly set to false. - It is `connectiontimeout`, NOT `connectionTimeout`. - Document default values.
…ieve, POP3, and TLS This includes the following major corrections: IMAP: - `auth.requireSSL`: This does not enforce TLS for authentication with OIDC - `disabledCaps`: Make clear that capabilities are enabled but only not advertised - Negative values for `timeout` throw an error. - Option `provisionDefaultMailboxes` was undocumented. POP3: - Properly document `handlerchain`. ManageSieve: No major corrections. SMTP: - Properly document `handlerchain`. - `authRequired` does not enforce authentication. - `auth.announce` influences announcement for PLAIN/LOGIN but disables OIDC. - `auth.requireSSL` only disallows clear text for OIDC. - `disabledFeatures`: Make clear that the features are not disabled. - Update security recommendations and add some warnings. LMTP: - Properly document `handlerchain`. TLS: - Document all options. - Strongly recommend to use implicit TLS everywhere except port 25. - Update commands for PEM and keystore certs. - Add some examples for using ACME clients for proper certificates.
felixauringer
force-pushed
the
refactor-server-docs
branch
from
7345cd4 to
6bbec73
Compare
chibenwa
reviewed
May 15, 2026
Contributor
That's some legacy from the original contribution, removing it is the right call |
Arsnael
approved these changes
May 18, 2026
quantranhong1999
approved these changes
May 18, 2026
Contributor
No it's not a lot to ask on the contrary. We all know we need to make the documentation of James easier and more user-friendly with a better structure for a better adoption in general. Thank you very much for spending time on this, it adds great value! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Originally, I only wanted to update some documentation for ManageSieve after I did not include proper documentation in #2773 and #2808.
I noticed that every protocol had its own documentation for OIDC and PROXY protocol and introduced a new partial for OIDC and the common server configuration options.
As I found some inconsistencies between code and documented options, I also rewrote the documentation for the protocol-specific configuration options.
I know that this is a lot but I hope that you have a look at it at some time. I really think that these changes could make the configuration of James a little easier 🙂
A note regarding the extendable server: I noticed that building the docs throws some errors on master. All of them originate from the extendable server that includes partials incorrectly. As it is not included in the navigation and all included pages are also included in the distributed server, I just removed the docs for the extendable server altogether. It's a single commit, so I can drop it quickly if you have future plans to fix that part of the documentation.