clean up and explain more about siteUrl and fqdn IQSS#6071

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

@@ -1385,26 +1385,32 @@ It's also possible to change these values by stopping Payara, editing ``payara5/
 dataverse.fqdn
 ++++++++++++++
 
-If the Dataverse installation has multiple DNS names, this option specifies the one to be used as the "official" host name. For example, you may want to have dataverse.example.edu, and not the less appealing server-123.socsci.example.edu to appear exclusively in all the registered global identifiers, Data Deposit API records, etc.
+If the Dataverse installation has multiple DNS names, this option specifies the one to be used as the "official" hostname. For example, you may want to have ``dataverse.example.edu``, and not the less appealing ``server-123.example.edu`` to appear exclusively in all the registered global identifiers, etc.
 
 The password reset feature requires ``dataverse.fqdn`` to be configured.
 
-.. note::
-
-	Do note that whenever the system needs to form a service URL, by default, it will be formed with ``https://`` and port 443. I.e.,
-	``https://{dataverse.fqdn}/``
-	If that does not suit your setup, you can define an additional option, ``dataverse.siteUrl``, explained below.
+Configuring ``dataverse.fqdn`` is not enough. Read on for the importance of also setting ``dataverse.siteUrl``.
 
 .. _dataverse.siteUrl:
 
 dataverse.siteUrl
 +++++++++++++++++
 
-To configure the ``siteUrl`` JVM option, follow the procedure stated in :ref:`jvm-options` and specify the protocol, host and port number you would prefer to be used to advertise the URL for your Dataverse installation.
+``dataverse.siteUrl`` is used to configure the URL for your Dataverse installation that you plan to advertise to your users. As explained in the :ref:`installation <importance-of-siteUrl>` docs, this setting is critical for the correct operation of your installation.
+
+For example, your site URL could be https://dataverse.example.edu
+
+That is, even though the server might also be available at uglier URLs such as https://server-123.example.edu the site URL is the "official" URL.
+
+The ``dataverse.siteUrl`` JVM option can be configured by following the procedure under :ref:`jvm-options` or by editing ``domain.xml`` directly. You can specify the protocol, host, and port number. Your ``domain.xml`` file could look like this, for example:
+
+``<jvm-options>-Ddataverse.siteUrl=https://dataverse.example.edu</jvm-options>``
+
+Note that it's also possible to use the ``dataverse.fqdn`` as a variable, if you wish. Here's an example of this as well as a custom port (which is usually not necessary):
 
-For example, if editing domain.xml:
+``<jvm-options>-Ddataverse.siteUrl=https://${dataverse.fqdn}:444</jvm-options>``
 
-``<jvm-options>-Ddataverse.siteUrl=http://${dataverse.fqdn}:8080</jvm-options>``
+We are absolutely aware that it's confusing to have both ``dataverse.fqdn`` and ``dataverse.siteUrl``. https://github.com/IQSS/dataverse/issues/6636 is about resolving this confusion.
 
 dataverse.files.directory
 +++++++++++++++++++++++++

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

@@ -82,6 +82,8 @@ While Postgres can accomodate usernames and database names containing hyphens, i
 
 For more information, please see https://docs.payara.fish/documentation/payara-server/password-aliases/password-alias-asadmin-commands.html
 
+.. _importance-of-siteUrl:
+
 **IMPORTANT:** The installer will also ask for an external site URL for the Dataverse installation. It is *imperative* that this value be supplied accurately, or a long list of functions will be inoperable, including:
 
 - email confirmation links
@@ -134,10 +136,10 @@ Dataset Cannot Be Published
 
 Check to make sure you used a fully qualified domain name when installing the Dataverse Software. You can change the ``dataverse.fqdn`` JVM option after the fact per the :doc:`config` section.
 
-Got ERR_ADDRESS_UNREACHABLE while navigating on interface or API calls
+Got ERR_ADDRESS_UNREACHABLE While Navigating on Interface or API Calls
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If You are receiving an ``ERR_ADDRESS_UNREACHABLE`` while navigating the GUI or making an API call, make sure the ``siteUrl`` JVM option is defined. For details on how to set ``siteUrl``, please refer to :ref:`dataverse.siteUrl` from the :doc:`config` section. For context on why setting this option is necessary, refer to :ref:`dataverse.fqdn` from the :doc:`config` section.
+If you are receiving an ``ERR_ADDRESS_UNREACHABLE`` while navigating the GUI or making an API call, make sure the ``siteUrl`` JVM option is defined. For details on how to set ``siteUrl``, please refer to :ref:`dataverse.siteUrl` from the :doc:`config` section. For context on why setting this option is necessary, refer to :ref:`dataverse.fqdn` from the :doc:`config` section.
 
 Problems Sending Email
 ^^^^^^^^^^^^^^^^^^^^^^