diff --git a/.github/workflows/quickstart_mail_ci.yml b/.github/workflows/quickstart_mail_ci.yml index 2e68ee06ea..fdbb17d018 100644 --- 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 index 7461d7c48c..66a1d71d19 100644 --- a/mail/README.adoc +++ b/mail/README.adoc @@ -6,7 +6,7 @@ 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 @@ -14,13 +14,13 @@ The `mail` quickstart demonstrates how to send email using CDI and JSF and the d == 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: +- user01@james.local +- user02@james.local +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 user01@james.local, user02@james.local and user03@james.local. +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'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 ... - - + + - + - - + + ---- @@ -115,10 +139,10 @@ The `MyOtherMail` mail session is added to the `mail` subsystem and configured t - - - - + + + + ---- @@ -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'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'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::[] \ No newline at end of file +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 +``` \ No newline at end of file diff --git a/mail/pom.xml b/mail/pom.xml index 69b557d8ec..6df6c2de8c 100644 --- a/mail/pom.xml +++ b/mail/pom.xml @@ -48,6 +48,7 @@ 30.0.0.Final ${version.server} + 5.0.0.Final 4.2.0.Final 4.15.0 @@ -212,7 +213,7 @@ jsf - ROOT.war + ROOT.war 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 index dd84723c0e..fde3fd784e 100644 --- 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 wait = new WebDriverWait(driver, Duration.ofSeconds(30)); + Wait 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 wait = new WebDriverWait(driver, Duration.ofSeconds(30)); + Wait 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 wait = new WebDriverWait(driver, Duration.ofSeconds(30)); + Wait wait = new WebDriverWait(driver, Duration.ofSeconds(15)); WebElement submitButton = driver.findElement(By.id("imap_get_emails_btn")); submitButton.click();