This is an automated email from the ASF dual-hosted git repository. chibenwa pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit dfaff675a7f18fc4cbdab6cf077f5a63deb4f8d2 Author: Benoit TELLIER <[email protected]> AuthorDate: Sun Aug 23 23:56:34 2026 +0700 [DOC] Remove the 'basic' server --- docs/modules/servers/nav.adoc | 6 - docs/modules/servers/pages/basic/architecture.adoc | 4 - .../servers/pages/basic/configure/index.adoc | 213 --------------------- docs/modules/servers/pages/basic/context.adoc | 25 --- docs/modules/servers/pages/basic/help.adoc | 52 ----- docs/modules/servers/pages/basic/index.adoc | 21 -- docs/modules/servers/pages/basic/objectives.adoc | 30 --- .../modules/servers/pages/basic/self-hosting.notes | 96 ---------- docs/modules/servers/pages/index.adoc | 25 +-- 9 files changed, 2 insertions(+), 470 deletions(-) diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 58e95fe22c..222eadc0a7 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -2,12 +2,6 @@ ** xref:demo.adoc[] *** xref:servers:5-minute-demo.adoc[] *** xref:servers:15-minute-demo.adoc[] -** xref:basic/index.adoc[] -*** xref:basic/context.adoc[] -*** xref:basic/objectives.adoc[] -*** xref:basic/architecture.adoc[] -*** xref:basic/configure/index.adoc[] -*** xref:basic/help.adoc[] ** xref:distributed/index.adoc[] *** xref:distributed/objectives.adoc[] *** xref:distributed/architecture/index.adoc[] diff --git a/docs/modules/servers/pages/basic/architecture.adoc b/docs/modules/servers/pages/basic/architecture.adoc deleted file mode 100644 index 706900ac8f..0000000000 --- a/docs/modules/servers/pages/basic/architecture.adoc +++ /dev/null @@ -1,4 +0,0 @@ -= James Basic Server — Architecture -:navtitle: Architecture - -(TODO) diff --git a/docs/modules/servers/pages/basic/configure/index.adoc b/docs/modules/servers/pages/basic/configure/index.adoc deleted file mode 100644 index 66fe00d993..0000000000 --- a/docs/modules/servers/pages/basic/configure/index.adoc +++ /dev/null @@ -1,213 +0,0 @@ -= James Basic Mail Server Configuration -:navtitle: Configuration - -(Work in progress.) - -//// -== JIRA Issues - -* dnsservice.xml - DNS Service Configuration -> https://issues.apache.org/jira/browse/JAMES-3219 - ** Status: to be removed -* domainlist.xml - Domain List Configuration -> https://issues.apache.org/jira/browse/JAMES-3220 - ** Status: to be removed -* events.xml - Event system Configuration (Spring only) - ** Status: Spring only, so n/a -* fetchmail.xml- FetchMail Configuration (Spring only) - ** Status: Spring only, so n/a -* imapserver.xml - IMAP4 Configuration -> https://issues.apache.org/jira/browse/JAMES-3229 - ** Status: -* jmap.properties - JMAP Configuration (Guice only) -> https://issues.apache.org/jira/browse/JAMES-3230 - ** Status: -* lmtpserver.xml - LMTP Configuration -> https://issues.apache.org/jira/browse/JAMES-3231 - ** Status: -* mailrepositorystore.xml - Mail Repository Stores Configuration -> https://issues.apache.org/jira/browse/JAMES-3232 - ** Status: -* mailbox.xml - Mailbox Configuration (Spring only) - ** Status: Spring only, so n/a -* mailetcontainer.xml - Mailet Container Configuration -> https://issues.apache.org/jira/browse/JAMES-3233 - ** Status: -* pop3server.xml - POP3 Configuration -> https://issues.apache.org/jira/browse/JAMES-3234 - ** Status: -* mailbox.xml - Quota Configuration (Spring only) - ** Status: Spring only, so n/a -* recipientrewritetable.xml - Recipient Rewrite Table Configuration -> https://issues.apache.org/jira/browse/JAMES-3235 - ** Status: -* smtpserver.xml - SMTP Configuration -> https://issues.apache.org/jira/browse/JAMES-3236 - ** Status: -* usersrepository.xml - Users Configuration -> https://issues.apache.org/jira/browse/JAMES-3237 - ** Status: -* webadmin.properties - WebAdmin Configuration -> https://issues.apache.org/jira/browse/JAMES-3238 - ** Status: -* jmx.properties -> https://issues.apache.org/jira/browse/JAMES-3240 - ** Status: -* extensions.properties -> https://issues.apache.org/jira/browse/JAMES-3241 - ** Status: -* jwt_publickey -> https://issues.apache.org/jira/browse/JAMES-3242a - ** Status: -* healthcheck.properties -> https://issues.apache.org/jira/browse/JAMES-3243 - ** Status: -* listeners.xml -> https://issues.apache.org/jira/browse/JAMES-3244 - ** Status: ----- -Comment from chibenwa: -chibenwa on Jun 15 Member -Mailbox listeners allows to react upon users mailbox events like "message added", "message deleted"... - - @dleangen -dleangen on Jun 15 Author Member -Thanks! - - @dleangen -dleangen on Jun 15 Author Member -Sorry, are these the same as SMTP Hooks that are described on the old website? - -Where can I find examples of these? - - @chibenwa -chibenwa on Jun 15 Member -No it is different. - -SMTP hooks are to add functionalities to the SMTP protocols. - -Here MailboxListener allow to react upon any mailbox changes whatever the protocol. - -See http://james.apache.org/server/config-listeners.html - - @dleangen -dleangen on Jun 15 Author Member -Ah, hehe. Ok, makes sense. I read the page at the url you pasted. - -Are there any examples anywhere? - - @mbaechler -mbaechler on Jun 16 Member -If you look at example of users in the code, the quota-search feature is a good example : https://github.com/apache/james-project/blob/master/mailbox/plugin/quota-search-opensearch/src/main/java/org/apache/james/quota/search/opensearch/events/OpenSearchQuotaMailboxListener.java - -It allows to index quota usage per user into OpenSearch ----- -* managesieveserver.xml -> https://issues.apache.org/jira/browse/JAMES-3245 - ** Status: -* spring-server.xml - System Configuration - ** Status: Spring only, so n/a -* james-database.properties & META-INF/persistence.xml -> https://issues.apache.org/jira/browse/JAMES-3246 - ** Status: -* log4j.properties & logback.xml -> https://issues.apache.org/jira/browse/JAMES-3239 - ** Status: - - -== Configuration by feature - - * Domain names — provide the default domain names that ???? - * Database (james-database.properties) - * LMTP (lmtpserver.xml) - * POP3 (pop3server.xml) - * DNS (dnsservice.xml) - ** Waiting for confirmation: can this be removed from Basic? - * Loggin (logback.xml) - * James CLI (jmx.properties) - * Email rewriting (recipientrewritetable.xml) - * Guice extensions (extensions.properties) - * JWT (jwt_publickey) - * Mailets (mailetcontainer.xml) - * SMTP (smtpserver.xml) - * Health checks (healthcheck.properties) - * Mail storage (mailrepositorystore.xml) - * User storage (usersrepository.xml) - * IMAP (imapserver.xml) - * Mailbox event listeners (listeners.xml) - * Sieve filters (managesieveserver.xml) - * Web admin (webadmin.properties) - -== Configuration file index - - * Domain names (domainlist.xml) - * Database (james-database.properties) - * LMTP (lmtpserver.xml) - * POP3 (pop3server.xml) - * DNS (dnsservice.xml) - * Loggin (logback.xml) - * James CLI (jmx.properties) - * Email rewriting (recipientrewritetable.xml) - * Guice extensions (extensions.properties) - * JWT (jwt_publickey) - * Mailets (mailetcontainer.xml) - * SMTP (smtpserver.xml) - * Health checks (healthcheck.properties) - * Mail storage (mailrepositorystore.xml) - * User storage (usersrepository.xml) - * IMAP (imapserver.xml) - * Mailbox event listeners (listeners.xml) - * Sieve filters (managesieveserver.xml) - * Web admin (webadmin.properties) - - -== Notes -Jmx protocol is used by James cli to interact with the server. Jmx is known to be insecure, and we have as a project to rewrite the cli for james servers in order to rely on webadmin. - - - -Scenarios for address rewriting ----- -Comment from chibenwa: - -chibenwa on Jun 17 Member -https://github.com/apache/james-project/blob/master/src/site/xdoc/server/config-recipientrewritetable.xml (not yet deployed on current website :-( tries to provide wording about Recipient Rewriting and use cases. - - @chibenwa -chibenwa on Jun 17 Member -Maybe address rewriting needs to be moved in the concept part? - - @dleangen -dleangen on Jun 17 Author Member -Yes, definitely. Anything that requires knowledge of any concept should be there. ----- - -The following scenarios are examples of how you can use address rewriting: - -Group consolidation: Some organizations segment their internal businesses into separate domains that are based on business or technical requirements. This configuration can cause email messages to appear as if they come from separate groups or even separate organizations. - -The following example shows how an organization, Contoso, Ltd., can hide its internal subdomains from external recipients: - -Outbound messages from the northamerica.contoso.com, europe.contoso.com, and asia.contoso.com domains are rewritten so they appear to originate from a single contoso.com domain. All messages are rewritten as they pass through Edge Transport servers that provide SMTP connectivity between the whole organization and the Internet. - ----- -Comment from chibenwa: -chibenwa on Jun 17 Member -We speak of a domain alias here. I would more formulate it: - -External email can send emails to northamerica.contoso.com, europe.contoso.com, ... -Internal users can send email from northamerica.contoso.com, europe.contoso.com, ... ----- -Inbound messages to contoso.com recipients are relayed by the Edge Transport server to a Mailbox server. The message is delivered to the correct recipient based on the proxy address that's configured on the recipient's mailbox. - -Mergers and acquisitions: An acquired company might continue to run as a separate business, but you can use address rewriting to make the two organizations appear as if they're one integrated organization. - -The following example shows how Contoso, Ltd. can hide the email domain of the newly acquired company, Fourth Coffee: - -Contoso, Ltd. wants all outbound messages from Fourth Coffee's Exchange organization to appear as if they originate from contoso.com. All messages from both organizations are sent through the Edge Transport servers at Contoso, Ltd., where email messages are rewritten from [email protected] to [email protected]. - -Inbound messages to [email protected] are rewritten and routed to [email protected] mailboxes. Inbound messages that are sent to [email protected] are routed directly to Fourth Coffee's email servers. - -Partners: Many organizations use external partners to provide services for their customers, other organizations, or their own organization. To avoid confusion, the organization might replace the email domain of the partner organization with its own email domain. - -The following example shows how Contoso, Ltd. can hide a partner's email domain: - -Contoso, Ltd. provides support for the larger Wingtip Toys organization. Wingtip Toys wants a unified email experience for its customers, and it requires all messages from support personnel at Contoso, Ltd. to appear as if they were sent from Wingtip Toys. All outbound messages that relate to Wingtip Toys are sent through their Edge Transport servers, and all contoso.com email addresses are rewritten to wingtiptoys.com email addresses. - -Inbound messages for [email protected] are accepted by Wingtip Toy's Edge Transport servers, rewritten, and then routed to the [email protected] email address. - -Message properties modified by address rewriting - -A standard SMTP email message consists of a message envelope and message content. The message envelope contains information that's required for transmitting and delivering the message between SMTP messaging servers. The message content contains message header fields (collectively called the message header) and the message body. The message envelope is described in RFC 2821, and the message header is described in RFC 2822. - -When a sender composes an email message and submits it for delivery, the message contains the basic information that's required to comply with SMTP standards, such as a sender, a recipient, the date and time that the message was composed, an optional subject line, and an optional message body. This information is contained in the message itself and, by definition, in the message header. - -The sender's mail server generates a message envelope for the message by using the sender's and recipient's information found in the message header. It then transmits the message to the Internet for delivery to the recipient's messaging server. Recipients never see the message envelope because it's generated by the message transmission process, and it isn't actually part of the message. - -Address rewriting changes an email address by rewriting specific fields in the message header or message envelope. Address rewriting changes several fields in outbound messages, but only one field in inbound email messages. The following table shows which SMTP header fields are rewritten in outbound and inbound messages. - - - - -https://www.exim.org/exim-html-current/doc/html/spec_html/ch-address_rewriting.html -//// diff --git a/docs/modules/servers/pages/basic/context.adoc b/docs/modules/servers/pages/basic/context.adoc deleted file mode 100644 index f4704a9b0d..0000000000 --- a/docs/modules/servers/pages/basic/context.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= James Basic Server — Context -:navtitle: Context - -Email has been around in one form or another for more than 50 years. -It is arguably one of the most resilient applications or our day, and -may even be called **THE** killer app of our time. Most of us, if not -all but the most unfortunate, use email on a regular basis. If you are -reading this page over the web, it is almost 100% certain that you have -used and continue to use email. - -Despite its ubiquity, the vast majority of people do not control their -own email infrastructure. Although, unlike telecommunications or electricity -for example, the barriers to owning and maintaining your own infrastructure -are very low, individuals and companies alike usually defer to the large -email providers for this essential service. -Although relying on the big providers is easy, what they offer is often -limited and in some cases much more costly than it ought to be. - -The Apache James Community is dedicated to liberating email. Our mission -is to make email hosting both easy and fun. We do this by: - - * Providing an easy-to-use self-hosted server for amateur Operators - * Providing an extendable server for those more experienced Operators - * Providing a distributed solution for heavy-duty projects - * Ensuring that James remains a flexible, reliable technology platform diff --git a/docs/modules/servers/pages/basic/help.adoc b/docs/modules/servers/pages/basic/help.adoc deleted file mode 100644 index f4578cd707..0000000000 --- a/docs/modules/servers/pages/basic/help.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= James Basic Server — Where to get help -:navtitle: Help - -//// - -This information is based on the email discussion from here: - --> https://www.mail-archive.com/[email protected]/msg66420.html - -However, I am not satisfied that I have properly captured the community's -opinion, and there are only a few people who have contributed to the -thread. - -Would be good to have some comments on this content. - -It could just be that I don't like the content. But if that is what the -community thinks, then that is what we should write. - -//// - -//// -Comment this out until there is agreement. -== Warning - -Please note that if you want to try to use James, you are pretty -much on your own. - -James is intended for use only by the current committers, or perhaps only by -competent developers only who have the ability to understand the code as it -exists now and can make changes themselves without any help. What you see -is what you get. Take it or leave it. - -The James Community is made up of people who "scratch their own itch". -If you have a problem with the code or the documentation, then please -step up and fix it rather than asking for help. - -If you are a user who wants to try to use James, you should seriously -consider hiring a professional organization to help you. Most likely, -James is not for you. - -You can try filing issues, but there is absolutely no guarantee it will be -fixed. If you are lucky and a developer has the same problem as you, then -it may be fixed. Or if one of the developers is feeling particularly generous and wants -to volunteer their valuable time to help you, it may happen. There is no -way to know unless you try. - -On the other hand, the developers would **love** for you to do stuff that -they are not interested in doing, like documentation. If you don't know anything -about the code, it would be a good way to help out until you can eventually -join the exclusive committer club, too. -//// - -(Redo this once there is consensus in the community.) diff --git a/docs/modules/servers/pages/basic/index.adoc b/docs/modules/servers/pages/basic/index.adoc deleted file mode 100644 index a252b2018d..0000000000 --- a/docs/modules/servers/pages/basic/index.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= James Basic Mail Server -:navtitle: Basic - -The **James Basic Server** is intended for Operators -who are just getting initiated with operating their own -Self-Hosted mail server. - -The server is intended to be a mostly "out-of-the-box" solution. -With a few small interactions necessary to configure the system, you should -be up and running in no time with all the standard features. - -These documents will present all the concepts that underpin this server, -and will walk you through its installation and configuration. If you run into -trouble, we explain how you can get help from the James Community. - - * xref:basic/context.adoc[The context of contemporary email] - * xref:basic/objectives.adoc[Objectives and motivation of the Basic Server] - * xref:basic/concepts.adoc[Useful background concepts] - * xref:basic/architecture.adoc[Overview of architecture] - * xref:basic/configure/index.adoc[Configuration] - * xref:basic/help.adoc[Where to go for help] diff --git a/docs/modules/servers/pages/basic/objectives.adoc b/docs/modules/servers/pages/basic/objectives.adoc deleted file mode 100644 index 89f0b2b487..0000000000 --- a/docs/modules/servers/pages/basic/objectives.adoc +++ /dev/null @@ -1,30 +0,0 @@ -= James Basic Server — Objectives -:navtitle: Objectives - -The objective of the Basic Server is to be as simple and minimalistic as possible, -while still being useful. Many people wish to have a basic self-hosted mail server that they -can use without having to become a deep technical expert. -The Basic Server is intended to be an entry-level server that is accessible to -those who want a self-hosted mail server, but who don't want to have to learn about all the -complexities of email communications. - -This server is therefore intended to be the simplest to set up and use in -production. -Of all the James Servers, it has the least amount of dependencies and configurations. -If you are not sure which of the James servers is best for you, you should -probably choose this one. - -The default configuration of the Basic Server includes the following features: - - * Secure SMTP (SSL/TLS) over port 465 - * Secure IMAP4 (SSL/TLS) over port 993 - * Local Mailbox support - ** Files are stored locally on the filesystem - ** Optionally use a volume if you are a Docker or Kubernetes user - * Multi-domain (virtual domain) support - * Administration of users either via a command-line tool or the admin api - -We have disabled all of the insecure communications and require SSL. If you have -a specific requirement to use an insecure protocol, or if the above list does not -satisfy your needs, then after having successfully set up this server you may want -to move on to the xref:servers:distributed/extending.adoc[Distributed Server]. diff --git a/docs/modules/servers/pages/basic/self-hosting.notes b/docs/modules/servers/pages/basic/self-hosting.notes deleted file mode 100644 index 54e065c62b..0000000000 --- a/docs/modules/servers/pages/basic/self-hosting.notes +++ /dev/null @@ -1,96 +0,0 @@ -The name of the project is "Jame Self Hosting Sandbox", and I see the term "self hosting" in a few places... So it sounds like it is important, but what is that intended to mean? - -I would like to understand better the intention behind the term. - - - -I would say "self hosting" means individuals having bought a domain name and want to install their own mail server for hosting their personal emails. Volumetry is small. They want control on their data. - -One generally tricky point about this kind of set up is getting third parties (like eg GMail) trusting your setup. It would be important to document a checklist regarding Mail Exchange trust like: - - I'm not an open spam relay - MX record registered for my domain - Reverse DNS setted up for MX servers - SPF records setted up - DKIM signature setted up -(which is slightly external to James as DNS setup is required) - - - -A "how to" regarding this is a MUST have in my opinion http://james.apache.org/howTo/index.html - - - -Just a thought based on the ideas you wrote here... - -But what if the mission of James were to "help people self-host their email" as an alternative to providers like gmail etc. - -Right now James is very obscure and is only for total tekkie geeks. If we modify the target, perhaps this could be the mission. - -The way of accomplishing this is: - -Provide in-depth "concept" articles -Provide more "how tos" for important things -Make James easier to install and operate -wdyt? - - -It would be more like: - -Apache James give you the ability to "self-host" email. Many companies and individuals are unable to develop their own mail infrastructure, but often feel trapped into using services like gmail, yahoo, etc. James provides a low-cost alternative for those who desire the freedom to use email the way they want. - -Or something like that. - - - -Apache James give you the ability to "self-host" email. Many companies and individuals are unable to develop their own mail infrastructure, but often feel trapped into using services like gmail, yahoo, etc. James provides a low-cost alternative for those who desire the freedom to use email the way they want. - -This should be the goal of the Basic server. - -Regarding "Advanced server": - -Free email servers are generally old, written in complex languages (C) and extending their behavior is not one of there main concerns. - -Apache James Advanced server have been designed with extensibility in mind. It provides several extension mechanisms allowing you to easily configure and extend the behavior of your email server in order to make it fits your needs. Java and other JVM languages can be used to write your own extensions. -And for the Apache James Distributed server: - -Scaling out IMAP mail server is notoriously difficult, as Mail server generally relies on technologies that don't scale well. Apache James server had been designed on top of modern distributed middlewares that allow you to scale it out just like any other modern web applications, reducing the management overhead of large scale deployments. -We could be thinking of, regarding the testing server: - -Embed a tiny, zero external dependency, easy to configure, feature complete, testing mail server to test the email logics for your code. Could be run directly in your JVM tests or spawn via docker. -Would that go in your direction? - - -For the Basic server we should manage to be less "teckie oriented". - -However "Advanced servers" branding should be compelling for "teckies" and discourage other operators. - - -Very nice! - -That gives me an idea for the naming, then: - -Basic Server (for self-hosting - should be very simple) -Extendable Server (for customizing - can be more complex) -Advanced Server (for just about everything else, including "Distributed" - no holds barred) -wdyt? - - -In the wording above I really prefer the term Distributed Server to Advanced Server as (as my little description above in #9 (comment) demonstrates it) 'distributed server' addresses a all category of advanced users concerns. - -I prefer branding the "distributed" term as this is a selling argument. - - - -IMO the Advanced server should be configured as local per default but configurable to redundant if needed. - -Technically: let's use a default embedded derby database for it, but if needed the operator can connect it with a PostgresSQL server for instance. - - - - -https://dmatthews.org/email_auth.html -https://dmatthews.org/java_email.html - - - diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 53b0178fc1..351dfa53ff 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -1,7 +1,7 @@ = Apache James Mail Servers :navtitle: Servers -James offers five types of ready-made Mail Servers. The servers are intended +James offers four types of ready-made Mail Servers. The servers are intended for those with different needs, ranging from Operators who are interested in setting up a server for the first time, to experienced teams of Developers @@ -13,7 +13,6 @@ Mail Server with confidence. The available James Servers are: * <<demo,James Demo Mail Server>> - * <<basic,James Basic Mail Server>> * <<distributed,James Distributed Mail Server>> * <<postgres,James Postgres Mail Server>> * <<test,James Test Server>> @@ -22,8 +21,7 @@ If you are just checking out James for the first time, then we highly recommend investigating the servers in this order: . Initiate yourself with James by using the <<demo,Demo Server>> -. Install the <<basic,Basic Server>> -. If and only if the Basic Server is not enough, then try the <<extendable,Extendable Server>> +. Deploy the <<distributed,Distributed Server>>, or its <<postgres,Postgres variant>> [#demo] == James Demo Server @@ -33,25 +31,6 @@ the fuss is about. -[#basic] -== James Basic Mail Server - -If you just want to get up and running quickly, if you have very simple needs, -or you want to try deploying a mail server for the first time, then the -xref:basic/index.adoc[*Basic Server*] is the right choice for you. If you are -not sure which server you should be using, then this server is probably the right -choice. - -This server is intended to be the simplest to set up and use in production. -It has the least amount of complexity and configurations to worry about. -The last thing you need is -to have to resolve difficult issues on a production server when you have not -yet acquired the requisite knowledge to deal with those issues. Using the -xref:basic/index.adoc[*Basic Server*] will help you reduce the risk of running into -production issues. - - - [#distributed] == James Distributed Mail Server --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
