Added mail configuration info to installation and dev environment gui…

…des #3061

doc/sphinx-guides/source/developers/dev-environment.rst

@@ -221,6 +221,54 @@ Sometimes Netbeans will change ``/`` to ``/dataverse``. Sometimes it will delete
 
 The solution is to put the file back to how it was before Netbeans touched it. If anyone knows of an open Netbeans bug about this, please let us know.
 
+Configuring / Troubleshooting Mail Host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To send generated emails - an important part of user related development - Dataverse requires a mail host to be configured in Glassfish. The current default when running the Dataverse installer is mail.hmdc.harvard.edu -- though it may not be ideal for all of our development environments. There may be necessary adjustments to be made.
+
+If you’ve already run the installer, it’s no problem to have the default SMTP host in place. You can check what it’s currently set to via the Glassfish asadmin command:
+
+``asadmin get server.resources.mail-resource.mail/notifyMailSession.host``
+
+This command helps verify what host your domain is using to send mail. Even if it's the correct hostname, you may still need to adjust settings. If all else fails, there are some free SMTP service options available such as Gmail and MailGun. Let's find where we can configure it.
+
+1. First, navigate to your Glassfish admin console: http://localhost:4848
+2. From the left-side panel, select **JavaMail Sessions**
+3. You should see one session named **mail/notifyMailSession** -- click on that.
+
+From this window you can modify certain fields of your Dataverse's notifyMailSession, which is the JavaMail session for outgoing system email (such as on user signup or data publication). Two of the most important fields we need are:
+
+- **Mail Host:** The DNS name of the default mail server (e.g. smtp.gmail.com)
+- **Default User:** The username provided to your Mail Host when you connect to it (e.g. johndoe@gmail.com) 
+
+Most of the other defaults can safely be left as is. **Default Sender Address** indicates the address that your installation's emails are sent from. 
+
+If your user credentials for the SMTP server require a password, you'll need to configure some **Additional Properties** at the bottom.
+
+**IMPORTANT:** Before continuing, it's highly recommended that your Default User account does NOT use a password you share with other accounts, as one of the additional properties includes entering the Default User's password (without concealing it on screen). For smtp.gmail.com you can safely use an `app password <https://support.google.com/accounts/answer/185833?hl=en>`_ or create an extra Gmail account for use with your Dataverse dev environment.
+
+Authenticating yourself to a Mail Host can be tricky. As an example, we'll walk through setting up our JavaMail Session to use smtp.gmail.com as a host by way of SSL on port 465. Use the Add Property button to generate a blank property for each name/value pair.
+
+====================================== ==============================
+ Name Value
+====================================== ==============================
+mail.smtp.auth true
+mail.smtp.password [user's (*app*) password\*]
+mail.smtp.port 465
+mail.smtp.socketFactory.port 465
+mail.smtp.socketFactory.fallback false
+mail.smtp.socketFactory.class javax.net.ssl.SSLSocketFactory
+====================================== ==============================
+
+**\*WARNING**: Entering a password here will *not* conceal it on-screen. It’s recommended to use an *app password* (for smtp.gmail.com users) or utilize a dedicated/non-personal user account with SMTP server auths so that you do not risk compromising your password.
+
+Save these changes at the top of the page and restart your Glassfish server to try it out.
+
+These properties can be tailored to your own preferred mail service, but if all else fails these settings work fine with Dataverse development environments for your localhost.
+
++ If you're seeing a "Relay access denied" error in your Glassfish logs when your app attempts to send an email, double check your user/password credentials for the Mail Host you're using. 
++ If you're seeing a "Connection refused" / similar error upon email sending, try another port.
+
 Rebuilding Your Dev Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/sphinx-guides/source/installation/installation-main.rst

@@ -105,10 +105,60 @@ Check to make sure you used a fully qualified domain name when installing Datave
 Problems Sending Email
 ++++++++++++++++++++++
 
-You can confirm the SMTP server being used with this command:
+If your Dataverse installation is not sending system emails, you may need to provide authentication for your mail host. First, double check the SMTP server being used with this Glassfish asadmin command:
 
 ``asadmin get server.resources.mail-resource.mail/notifyMailSession.host``
 
+This should return the DNS of the mail host you configured during or after installation. mail/notifyMailSession is the JavaMail Session that's used to send emails to users. 
+
+If the command returns a host you don't want to use, you can modify your notifyMailSession with the Glassfish ``asadmin set`` command with necessary options (`click here for the manual page <https://docs.oracle.com/cd/E18930_01/html/821-2433/set-1.html>`_), or via the admin console at http://localhost:4848 with your domain running. 
+
+If your mail host requires a username/password for access, continue to the next section.
+
+Mail Host Configuration & Authentication
+++++++++++++++++++++++++++++++++++++++++
+
+If you need to alter your mail host address, user, or provide a password to connect with, these settings are easily changed in the Glassfish admin console. 
+
+In a browser, with your domain online, navigate to http://localhost:4848 and on the side panel find JavaMail Sessions. By default, Dataverse uses a session named mail/notifyMailSession for routing outgoing emails. Click this mail session in the window to modify it.
+
+When fine tuning your JavaMail Session, there are a number of fields you can edit. The most important are:
+
++ **Mail Host:** Desired mail host’s DNS address (e.g. smtp.gmail.com)
++ **Default User:** Username mail host will recognize (e.g. user\@gmail.com)
++ **Default Sender Address:** Email address that your Dataverse will send mail from
+
+Depending on the SMTP server you're using, you may need to add additional properties at the bottom of the page (below "Advanced").
+
+From the "Add Properties" utility at the bottom, use the “Add Property” button for each entry you need, and include the name / corresponding value as needed. Descriptions are optional, but can be used for your own organizational needs. 
+
+**Note:** These properties are just an example. You may need different/more/fewer properties all depending on the SMTP server you’re using.
+
+============================== ==============================
+ Name Value
+============================== ==============================
+mail.smtp.auth true
+mail.smtp.password [Default User password*]
+mail.smtp.port [Port number to route through]
+============================== ==============================
+
+**\*WARNING**: Entering a password here will *not* conceal it on-screen. It’s recommended to use an *app password* (for smtp.gmail.com users) or utilize a dedicated/non-personal user account with SMTP server auths so that you do not risk compromising your password.
+
+If your installation’s mail host uses SSL (like smtp.gmail.com) you’ll need these name/value pair properties in place:
+
+====================================== ==============================
+ Name Value
+====================================== ==============================
+mail.smtp.socketFactory.port 465
+mail.smtp.port 465
+mail.smtp.socketFactory.fallback false
+mail.smtp.socketFactory.class javax.net.ssl.SSLSocketFactory
+====================================== ==============================
+
+Be sure you save the changes made here and then restart your Glassfish server to test it out.
+
+For further needs specific to your institution’s mail server, your resident system administrator or IT helpdesk can provide more information / support about your org / institute's mail host.
+
 UnknownHostException While Deploying
 ++++++++++++++++++++++++++++++++++++