Merge pull request #776 from yersan/WFLY-18491

[WFLY-18491] Mail Quickstart Common Enhancements

.github/workflows/quickstart_mail_ci.yml

@@ -0,0 +1,17 @@
+name: WildFly Mail Quickstart CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'mail/**'
+      - '.github/workflows/quickstart_ci.yml'
+
+jobs:
+  call-quickstart_ci:
+    uses: ./.github/workflows/quickstart_ci.yml
+    with:
+      QUICKSTART_PATH: mail
+      TEST_PROVISIONED_SERVER: true
+      TEST_OPENSHIFT: false
+      MATRIX_OS: '"ubuntu-latest"'

.github/workflows/quickstart_mail_ci_before.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# Start apache James with the required configuration
+docker run -d --rm --name "apache-james" \
+  -p 1465:465 \
+  -p 1993:993 \
+  -p 1025:25 \
+  -p 1110:110 \
+  -p 1587:587 \
+  -p 1143:143 \
+  -v ${GITHUB_WORKSPACE}/quickstarts/mail/mail-server-conf/imapserver.xml:/root/conf/imapserver.xml \
+  -v ${GITHUB_WORKSPACE}/quickstarts/mail/mail-server-conf/pop3server.xml:/root/conf/pop3server.xml \
+  -v ${GITHUB_WORKSPACE}/quickstarts/mail/mail-server-conf/smtpserver.xml:/root/conf/smtpserver.xml \
+  apache/james:demo-3.8.0

mail/README.adoc

@@ -6,34 +6,66 @@ include::../shared-doc/attributes.adoc[]
 :technologies: JavaMail, CDI, JSF
 
 [abstract]
-The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with {productName}.
+The `mail` quickstart demonstrates how to send and receive emails using CDI and JSF and with custom Mail provider configured in {productName}.
 
 :standalone-server-type: default
 :archiveType: war
 :restoreScriptName: remove-mail-session.cli
 
 == What is it?
 
-The `mail` quickstart demonstrates sending email with the use of _CDI_ (Contexts and Dependency Injection) and _JSF_ (JavaServer Faces) in {productNameFull}.
+The `mail` quickstart demonstrates sending and receiving emails with the use of _CDI_ (Contexts and Dependency Injection) and _JSF_ (JavaServer Faces) in {productNameFull}.
 
 The mail provider is configured in the `mail` subsystem of the `__{jbossHomeName}__/standalone/configuration/standalone.xml` configuration file if you are running a standalone server or in the `__{jbossHomeName}__/domain/configuration/domain.xml` configuration file if you are running in a managed domain.
 
 You can use the default mail provider that comes out of the box with {productName}. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider.
 
-This example is a web application that takes `To`, `From`, `Subject`, and `Message Body` input and sends mail to that address. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection.
+This example is a web application that takes `To`, `From`, `Subject`, and `Message Body` input and sends mail using SMTP. These emails can be later read by using IMAP or POP3. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection.
 
 // System Requirements
 include::../shared-doc/system-requirements.adoc[leveloffset=+1]
 // Use of {jbossHomeName}
 include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
 
 [[configure_an_smtp_server_on_your_local_machine]]
-== Configure an SMTP Server on Your Local Machine
+== Configure a Mail Server on Your Local Machine
 
-This quickstart expects that you have an SMTP mail server running on your machine and configured for the default port `localhost:25`.
-To configure an SMTP mail server, consult the documentation for your operating system. It is beyond the scope of this quickstart to provide these instructions.
+To run the Mail Quickstart, you need a Mail Server configured with the following protocols and ports:
 
-If you do not configure an SMTP mail server on your local machine, you will see the exception `MailConnectException:  Couldn't connect to host, port: localhost, 25; timeout -1;` when you access the application and attempt to send an email.
+- SMTP port:1025
+- POP3 port:1110
+- IMAP port:1143
+
+In addition, the Mail Subsystem configuration and the test cases expect you have the following Mail accounts configured on your Mail Server:
+
+- [email protected]
+- [email protected]
+
+You can use any Mail Server you consider, although to facilitate this task, you will find under the Mail Quickstart root directory a docker compose file prepared to launch an Apache James Mail server with all the required configuration. You will need to have installed a Container Engine capable of work with Docker compose files and Linux images. The following command assumes you have https://podman.io/[Podman] and https://docs.podman.io/en/latest/markdown/podman-compose.1.html[Podman Compose] installed in your local environment.
+
+To launch the Apache James Mail server, open the terminal and navigate to the Mail Quickstart root directory and execute the following:
+
+```
+$ podman compose up --wait
+>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<<
+
+[+] Running 1/1
+ ✔ Container apache-james  Healthy
+```
+
+NOTE: The Apache James server is configured without allowing the relay of the emails to external addresses that are not configured in the server. When you are sending / receiving emails with this server, you have to use the accounts shipped with the apache James demo image. These are the accounts available out of the box: [email protected], [email protected] and [email protected].
+All accounts use the same password: `1234`
+
+Once you have finished with the Mail Quickstart, you can shutdown and remove the Apache James Mail server with the following command:
+
+```
+$ podman compose down --volumes
+>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<<
+
+[+] Running 2/1
+ ✔ Container apache-james  Removed
+ ✔ Network mail_default    Removed
+```
 
 // Back Up the {productName} Standalone Server Configuration
 include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
@@ -50,7 +82,7 @@ You configure the custom mail session in {productName} by running Management CLI
 * xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
 * xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.
 
-. Review the `configure-mail-session.cli` file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom `MyOtherMail` mail session and configures it to use the custom outbound socket binding ports.
+. Review the `configure-mail-session.cli` file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom `MyOtherMail` mail session and configures it to use the custom outbound socket binding ports and default user credentials for SMTP and IMAP.
 . Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server:
 +
 [source,subs="+quotes,attributes+",options="nowrap"]
@@ -82,14 +114,14 @@ The following `outbound-socket-binding` groups are added to the `standard-socket
 <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
   ...
   </outbound-socket-binding>
-  <outbound-socket-binding name="my-smtp-binding">
-      <remote-destination host="localhost" port="25"/>
+  <outbound-socket-binding name="my-imap-binding">
+      <remote-destination host="localhost" port="1143"/>
   </outbound-socket-binding>
   <outbound-socket-binding name="my-pop3-binding">
-      <remote-destination host="localhost" port="110"/>
+      <remote-destination host="localhost" port="1110"/>
   </outbound-socket-binding>
-  <outbound-socket-binding name="my-imap-binding">
-      <remote-destination host="localhost" port="143"/>
+  <outbound-socket-binding name="my-smtp-binding">
+     <remote-destination host="localhost" port="1025"/>
   </outbound-socket-binding>
 </socket-binding-group>
 ----
@@ -102,10 +134,10 @@ The `MyOtherMail` mail session is added to the `mail` subsystem and configured t
    <mail-session name="default" jndi-name="java:jboss/mail/Default">
       <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    </mail-session>
-   <mail-session name="MyOtherMail" jndi-name="java:jboss/mail/MyOtherMail">
-      <smtp-server password="pass" username="nobody" tls="true" outbound-socket-binding-ref="my-smtp-binding"/>
-      <pop3-server outbound-socket-binding-ref="my-pop3-binding"/>
-      <imap-server password="pass" username="nobody" outbound-socket-binding-ref="my-imap-binding"/>
+   <mail-session name="MyOtherMail" debug="true" jndi-name="java:jboss/mail/MyOtherMail">
+     <smtp-server outbound-socket-binding-ref="my-smtp-binding" username="[email protected]" password="1234"/>
+     <pop3-server outbound-socket-binding-ref="my-pop3-binding"/>
+     <imap-server outbound-socket-binding-ref="my-imap-binding" username="[email protected]" password="1234"/>
    </mail-session>
 </subsystem>
 ----
@@ -115,9 +147,14 @@ include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]
 
 == Access the Application
 
-The application will be running at the following URL: http://localhost:8080/{artifactId}/.
+The application will be running at the following URL: http://localhost:8080/{artifactId}/[http://localhost:8080/{artifactId}/^].
+
+NOTE: If you see `Error processing request` in the browser when you access the application and attempt to send email, followed by `jakarta.servlet.ServletException: MailConnectException: Couldn&#39;t connect to host, port: localhost, 1025; timeout -1; nested exception is: java.net.ConnectException: Connection refused`, make sure you followed the instructions above to xref:configure_an_smtp_server_on_your_local_machine[Configure an SMTP Server on Your Local Machine].
 
-NOTE: If you see `Error processing request` in the browser when you access the application and attempt to send email, followed by `jakarta.servlet.ServletException: MailConnectException: Couldn&#39;t connect to host, port: localhost, 25; timeout -1; nested exception is: java.net.ConnectException: Connction refused`, make sure you followed the instructions above to xref:configure_an_smtp_server_on_your_local_machine[Configure an SMTP Server on Your Local Machine].
+NOTE: If you are using the Mail server shipped with this Quickstart and see `Error sending the Email. Invalid Addresses` in the browser when you attempt to send email, make sure you are sending your email to an existing account configured in the Mail Server since by default Apache James demo image is shipped with relay disabled. By default, Apache James demo image has the following accounts configured: [email protected], [email protected] and [email protected].
+
+// Server Distribution Testing
+include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
 
 // Undeploy the Quickstart
 include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
@@ -148,6 +185,11 @@ include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[levelof
 // Debug the Application
 include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
 
+// Build and run sections for other environments/builds
+ifndef::ProductRelease,EAPXPRelease[]
+include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
+endif::[]
+
 //*************************************************
 // Product Release content only
 //*************************************************
@@ -156,4 +198,4 @@ ifdef::ProductRelease[]
 // Quickstart not compatible with OpenShift
 include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1]
 
-endif::[]
+endif::[]

mail/configure-mail-session.cli

@@ -7,14 +7,14 @@ batch
 /subsystem=mail/mail-session=MyOtherMail:add(jndi-name=java:jboss/mail/MyOtherMail,debug=true)
 
 # Configure the custom SMTP, POP3, and IMAP socket binding groups
-/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost,port=25)
-/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost,port=110)
-/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost,port=143)
+/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost,port=1025)
+/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost,port=1110)
+/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost,port=1143)
 
 # Add the custom socket binding groups to the custom MyOtherMail mail session
-/subsystem=mail/mail-session=MyOtherMail/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding,username=nobody,password=pass,tls=true)
+/subsystem=mail/mail-session=MyOtherMail/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding,username="[email protected]",password=1234)
 /subsystem=mail/mail-session=MyOtherMail/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding)
-/subsystem=mail/mail-session=MyOtherMail/server=imap:add(outbound-socket-binding-ref=my-imap-binding,username=nobody,password=pass)
+/subsystem=mail/mail-session=MyOtherMail/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username="[email protected]",password=1234)
 
 # Run the batch commands
 run-batch

mail/docker-compose.yaml

@@ -0,0 +1,22 @@
+services:
+  quickstart-mail-server:
+    image: "apache/james:demo-3.8.0"
+    container_name: "apache-james"
+    hostname: "james.local"
+    ports:
+      - "1465:465"
+      - "1993:993"
+      - "1025:25"
+      - "1110:110"
+      - "1587:587"
+      - "1143:143"
+    volumes:
+      - ./mail-server-conf/imapserver.xml:/root/conf/imapserver.xml
+      - ./mail-server-conf/pop3server.xml:/root/conf/pop3server.xml
+      - ./mail-server-conf/smtpserver.xml:/root/conf/smtpserver.xml
+    healthcheck:
+      test: [ "CMD-SHELL", "/bin/james-cli -h 127.0.0.1 -p 9999 ListUsers | grep -q '[email protected]'" ]
+      interval: 5s
+      timeout: 1m
+      retries: 5
+      start_period: 20s

mail/mail-server-conf/imapserver.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<imapservers>
+    <imapserver enabled="true">
+        <jmxName>imapserver</jmxName>
+        <bind>0.0.0.0:143</bind>
+        <connectionBacklog>200</connectionBacklog>
+        <tls socketTLS="false" startTLS="true">
+            <privateKey>file://conf/private.key</privateKey>
+            <certificates>file://conf/private.csr</certificates>
+        </tls>
+        <connectionLimit>0</connectionLimit>
+        <connectionLimitPerIP>0</connectionLimitPerIP>
+        <plainAuthDisallowed>false</plainAuthDisallowed>
+        <gracefulShutdown>false</gracefulShutdown>
+    </imapserver>
+</imapservers>

mail/mail-server-conf/pop3server.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<pop3servers>
+    <pop3server enabled="true">
+        <jmxName>pop3server</jmxName>
+        <bind>0.0.0.0:110</bind>
+        <connectionBacklog>200</connectionBacklog>
+        <tls socketTLS="false" startTLS="true">
+            <privateKey>file://conf/private.key</privateKey>
+            <certificates>file://conf/private.csr</certificates>
+        </tls>
+        <connectiontimeout>1200</connectiontimeout>
+        <connectionLimit>0</connectionLimit>
+        <connectionLimitPerIP>0</connectionLimitPerIP>
+        <handlerchain>
+            <handler class="org.apache.james.pop3server.core.CoreCmdHandlerLoader"/>
+        </handlerchain>
+    </pop3server>
+</pop3servers>

mail/mail-server-conf/smtpserver.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<smtpservers>
+    <smtpserver enabled="true">
+        <jmxName>smtpserver-global</jmxName>
+        <bind>0.0.0.0:25</bind>
+        <connectionBacklog>200</connectionBacklog>
+        <tls socketTLS="false" startTLS="true">
+            <privateKey>file://conf/private.key</privateKey>
+            <certificates>file://conf/private.csr</certificates>
+        </tls>
+        <connectiontimeout>360</connectiontimeout>
+        <connectionLimit>0</connectionLimit>
+        <connectionLimitPerIP>0</connectionLimitPerIP>
+        <auth>
+            <announce>never</announce>
+            <requireSSL>false</requireSSL>
+        </auth>
+        <verifyIdentity>false</verifyIdentity>
+        <maxmessagesize>0</maxmessagesize>
+        <addressBracketsEnforcement>true</addressBracketsEnforcement>
+        <smtpGreeting>Apache JAMES awesome SMTP Server</smtpGreeting>
+        <handlerchain>
+            <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
+            <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
+        </handlerchain>
+    </smtpserver>
+</smtpservers>