Clean up, minor docs and CI

wildfly · Nov 15, 2023 · 15fc3cf · 15fc3cf
1 parent 721ee01
commit 15fc3cf
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 33 deletions.
diff --git a/.github/workflows/quickstart_mail_ci.yml b/.github/workflows/quickstart_mail_ci.yml
@@ -1,13 +1,12 @@
 name: WildFly Mail Quickstart CI
 
-#on:
-#  pull_request:
-#    types: [opened, synchronize, reopened, ready_for_review]
-#    paths:
-#      - 'mail/**'
-#      - '.github/workflows/quickstart_ci.yml'
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'mail/**'
+      - '.github/workflows/quickstart_ci.yml'
 
-on: workflow_dispatch
 jobs:
   call-quickstart_ci:
     uses: ./.github/workflows/quickstart_ci.yml

diff --git a/mail/README.adoc b/mail/README.adoc
@@ -6,21 +6,21 @@ 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 a custom Mail provider that ships with {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]
@@ -30,23 +30,47 @@ 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
 
-To run the Mail quickstart, we need an SMTP mail server running on your machine and configured for the port `localhost:1025`.
-One way to accomplish it, is by starting a docker container. Execute the following command to have an Apache James Mail server configured with the expected ports used by this quickstart:
+To run the Mail Quickstart, you need a Mail Server configured to allow the following protocols and ports:
 
-```
+- SMTP port:1025
+- POP3 port:1110
+- IMAP port:1143
 
-```
+In addition, the Mail Subsystem configuration and the test cases expect you have the following users configured:
 
+- [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. The following command assumes you have Podman and Podman Compose installed in your local environment. Open the terminal and navigate to the Mail Quickstart root folder and execute the following:
 
-Kafka service we will use its Docker container
+```
+$ podman compose up
+>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<<
+
+[+] Running 2/2
+ ✔ Network mail_default    Created                                                                                                                                            0.0s
+ ✔ Container apache-james  Created                                                                                                                                            0.1s
+Attaching to apache-james
+apache-james  | Generating a RSA private key
+apache-james  | ...............++++
+apache-james  | ..................................++++
+apache-james  | writing new private key to '/root/conf/private.key'
+apache-james  | -----
+...
+apache-james  | 14:49:20.501 [INFO ] o.a.j.GuiceJamesServer - JAMES server started
+apache-james  | AddDomain command executed sucessfully in 2094 ms.
+apache-james  | AddUser command executed sucessfully in 1302 ms.
+apache-james  | AddUser command executed sucessfully in 972 ms.
+apache-james  | AddUser command executed sucessfully in 1904 ms.
+```
 
-This quickstart expects that you have an SMTP mail server running on your machine and configured for the default port `localhost:1025`.
+Once started, wait until Apache James server has started and the users are configured.
 
+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 accounts configured in the Mail server. These are the out of the box accounts that are shipped by default with the Apache James Demo image [email protected], [email protected] and [email protected].
+All accounts use the same password: `1234`
 
-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 stop and remove the Apache James server execute the following:
 
-If you do not configure an SMTP mail server on your local machine, you will see the exception `MailConnectException:  Couldn&#39;t connect to host, port: localhost, 25; timeout -1;` when you access the application and attempt to send an email.
 
 // Back Up the {productName} Standalone Server Configuration
 include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
@@ -95,14 +119,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>
 ----
@@ -115,10 +139,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>
 ----
@@ -130,7 +154,7 @@ include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]
 
 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, 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 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].
 
 // Server Distribution Testing
 include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
@@ -177,4 +201,16 @@ ifdef::ProductRelease[]
 // Quickstart not compatible with OpenShift
 include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1]
 
-endif::[]
+endif::[]
+
+== Shutdown and remove the Mail Server
+If you have launched the Apache James Mail server available from this quickstart, you can shutdown it and clean up the volumes and network assigned by using 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                                                                                                                                           10.4s
+ ✔ Network mail_default    Removed
+```
diff --git a/mail/pom.xml b/mail/pom.xml
@@ -48,6 +48,7 @@
         <version.server>30.0.0.Final</version.server>
         <!-- The versions for BOMs, Packs and Plugins -->
         <version.bom.ee>${version.server}</version.bom.ee>
+        <version.pack.cloud>5.0.0.Final</version.pack.cloud>
         <version.plugin.wildfly>4.2.0.Final</version.plugin.wildfly>
 
         <version.org.seleniumhq.selenium>4.15.0</version.org.seleniumhq.selenium>
@@ -212,7 +213,7 @@
                                 <layer>jsf</layer>
                             </layers>
                             <!-- deploys the quickstart on root web context -->
-                            <runtimeName>ROOT.war</runtimeName>
+                            <name>ROOT.war</name>
                             <packaging-scripts>
                                 <packaging-script>
                                     <scripts>

diff --git a/mail/src/test/java/org/jboss/as/quickstarts/mail/MailTestCaseIT.java b/mail/src/test/java/org/jboss/as/quickstarts/mail/MailTestCaseIT.java
@@ -58,7 +58,7 @@ public void cleanUp() {
 
     @Test
     public void a_testSMTP() {
-        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(30));
+        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(15));
 
         WebElement from = driver.findElement(By.id("smtp_from"));
         WebElement to = driver.findElement(By.id("smtp_to"));
@@ -88,7 +88,7 @@ public void a_testSMTP() {
 
     @Test
     public void b_retrievePOP3() {
-        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(30));
+        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(15));
 
         WebElement user = driver.findElement(By.id("pop3_user"));
         WebElement password = driver.findElement(By.id("pop3_password"));
@@ -120,7 +120,7 @@ public void b_retrievePOP3() {
 
     @Test
     public void c_retrieveIMAP() {
-        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(30));
+        Wait<WebDriver> wait = new WebDriverWait(driver, Duration.ofSeconds(15));
 
         WebElement submitButton = driver.findElement(By.id("imap_get_emails_btn"));
         submitButton.click();