Better management of email.php configuration (CO-1975)

comanage-registry-base/comanage_utils.sh

@@ -377,24 +377,67 @@ function comanage_utils::prepare_email_config() {
     local email_config
     email_config="$COMANAGE_REGISTRY_DIR/local/Config/email.php"
 
-    if [ ! -e "$email_config" ]; then
-        cat > "$email_config" <<EOF
+    # File already exists so return.
+    if [[ -e "$email_config" ]]; then
+        return
+    fi
+
+    # File does not exist so create it.
+    local php_string
+
+    read -r -d '' php_string <<'EOF'
 <?php
 
 class EmailConfig {
 
-  public \$default = array(
-    'from' => ${COMANAGE_REGISTRY_EMAIL_FROM:-array('account@gmail.com' => 'Registry')},
-    'transport' => '${COMANAGE_REGISTRY_EMAIL_TRANSPORT:-Smtp}',
-    'host' => '${COMANAGE_REGISTRY_EMAIL_HOST:-tls://smtp.gmail.com}',
-    'port' => ${COMANAGE_REGISTRY_EMAIL_PORT:-465},
-    'username' => '${COMANAGE_REGISTRY_EMAIL_ACCOUNT:-account@gmail.com}',
-    'password' => '${COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD:-password}'
-  );
-}
+  public $default = array(
 EOF
-        echo "Wrote new email configuration file ${email_config}" > "$OUTPUT"
+
+    php_string+=$'\n\t\t'
+
+    # Prefer the array of sender email and name if available, but
+    # if not then prefer the sender email over the older default
+    # and if neither is set use a default since the 'from' 
+    # configuration key is always required.
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}" && -n "${COMANAGE_REGISTRY_EMAIL_FROM_NAME}" ]]; then
+        php_string+="'from' => array('${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}' => '${COMANAGE_REGISTRY_EMAIL_FROM_NAME}'),"
+    elif [[ -n "${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}" && -z "${COMANAGE_REGISTRY_EMAIL_FROM_NAME}" ]]; then
+        php_string+="'from' => '${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}',"
+    elif [[ -n "${COMANAGE_REGISTRY_EMAIL_FROM}" && -z "${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}" ]]; then
+        php_string+="'from' => '${COMANAGE_REGISTRY_EMAIL_FROM}',"
+    elif [[ -z "${COMANAGE_REGISTRY_EMAIL_FROM}" ]]; then
+        php_string+="'from' => 'you@localhost',"
     fi
+
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_TRANSPORT}" ]]; then
+        php_string+=$'\n\t\t'
+        php_string+="'transport' => '${COMANAGE_REGISTRY_EMAIL_TRANSPORT}',"
+    fi
+
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_HOST}" ]]; then
+        php_string+=$'\n\t\t'
+        php_string+="'host' => '${COMANAGE_REGISTRY_EMAIL_HOST}',"
+    fi
+
+    # The value of port is an integer.
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_PORT}" ]]; then
+        php_string+=$'\n\t\t'
+        php_string+="'port' => ${COMANAGE_REGISTRY_EMAIL_PORT},"
+    fi
+
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_ACCOUNT}" ]]; then
+        php_string+=$'\n\t\t'
+        php_string+="'username' => '${COMANAGE_REGISTRY_EMAIL_ACCOUNT}',"
+    fi
+
+    if [[ -n "${COMANAGE_REGISTRY_EMAIL_PASSWORD}" ]]; then
+        php_string+=$'\n\t\t'
+        php_string+="'password' => '${COMANAGE_REGISTRY_EMAIL_PASSWORD}',"
+    fi
+
+    php_string+=$'\n\t\t);\n\n}\n';
+
+    printf "%s" "$php_string" > $email_config
 }
 
 ##########################################

docs/comanage-registry-common-environment-variables.md

@@ -107,50 +107,77 @@ provided that the file it points to exists and is readable.
 
 ```COMANAGE_REGISTRY_EMAIL_FROM```
 
-* Description: Default email "From" for emails sent by COmanage Registry
+* Deprecated. Use the combination of ```COMANAGE_REGISTRY_EMAIL_FROM_EMAIL``` and
+```COMANAGE_REGISTRY_EMAIL_FROM_NAME``` instead.
+
+``` COMANAGE_REGISTRY_EMAIL_FROM_EMAIL```
+
+* Description: Default email "From" for emails sent by COmanage Registry. This is the email part
+of the sender array. 
 * Required: yes
-* Default: ```array('account@gmail.com' => 'Registry')```
+* Default: ```you@localhost```
 * Example: registry@my.org
+* Note: The name part of the sender array is specified using ```COMANAGE_REGISTRY_EMAIL_FROM_NAME```.
+When used together the resulting PHP is
+    ```
+    '${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}' => '${COMANAGE_REGISTRY_EMAIL_FROM_NAME}'
+    ```
+* Note: \[[3](#note03)\]
+* Note: This is a [CakePHP email configuration value](https://book.cakephp.org/2.0/en/core-utility-libraries/email.html).
+
+``` COMANAGE_REGISTRY_EMAIL_FROM_NAME```
+
+* Description: Default email "From" for emails sent by COmanage Registry. This is the name part
+of the sender array. 
+
+* Required: yes
+* Default: none
+* Example: Registry
+* Note: The email part of the sender array is specified using ```COMANAGE_REGISTRY_EMAIL_FROM_EMAIL```.
+When used together the resulting PHP is
+    ```
+    '${COMANAGE_REGISTRY_EMAIL_FROM_EMAIL}' => '${COMANAGE_REGISTRY_EMAIL_FROM_NAME}'
+    ```
 * Note: \[[3](#note03)\]
 * Note: This is a [CakePHP email configuration value](https://book.cakephp.org/2.0/en/core-utility-libraries/email.html).
 
 ```COMANAGE_REGISTRY_EMAIL_TRANSPORT```
 
 * Description: Email transport
-* Required: yes
-* Default: Smtp
+* Required: no
+* Default: none
 * Example: Smtp
 * Note: \[[3](#note03)\]
 
 ```COMANAGE_REGISTRY_EMAIL_HOST```
 
 * Description: Email server host
-* Required: yes
-* Default: ```tls://smtp.gmail.com```
-* Example: smtp.my.org
+* Required: no
+* Default: none
+* Example: tls://smtp.gmail.com
 * Note: \[[3](#note03)\]
 
 ```COMANAGE_REGISTRY_EMAIL_PORT```
 
 * Description: Email server port
-* Required: yes
-* Default: 465
-* Example: 25
+* Required: no
+* Default: none
+* Example: 465
 * Note: \[[3](#note03)\]
 
 ```COMANAGE_REGISTRY_EMAIL_ACCOUNT```
 
 * Description: Email server account
 * Required: no
-* Default: account@gmail.com
+* Default: none
 * Example: comanage-registry-smtp@my.org
 * Note: \[[3](#note03)\]
 
 ```COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD```
 
 * Description: Email server account password
 * Required: no
-* Default: password
+* Default: none
 * Example: Sw5x71ToBHBEr4VqpRxD
 * Note: \[[3](#note03)\]
 
@@ -194,7 +221,9 @@ shares a bind mounted directory with the COmanage Registry image.
 started and written to the persistent volume (or bind mount) in the 
 configuration file ```security.salt```. Later changes to the environment
 variable are *not* reflected in the file which must be
-edited directly.
+edited directly. If not using a persistent volume or bind mount or otherwise
+providing the file ```security.salt``` then you must configure this environment
+variable in order that the same value persists between container restarts.
 
 ```COMANAGE_REGISTRY_SECURITY_SEED```
 
@@ -206,7 +235,9 @@ edited directly.
 started and written to the persistent volume (or bind mount) in the 
 configuration file ```security.seed```. Later changes to the environment
 variable are *not* reflected in the file which must be
-edited directly.
+edited directly. If not using a persistent volume or bind mount or otherwise
+providing the file ```security.seed``` then you must configure this environment
+variable in order that the same value persists between container restarts.
 
 ```COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN```
 
@@ -240,15 +271,12 @@ edited directly.
 started and saved to the COmanage Registry database.  Later changes to the environment
 variable are *not* reflected in the database state.
 
-\[<a name="note02">2</a>\]: The environment variable is read the first time the container is
-started and written to the persistent volume (or bind mount) in the 
-configuration file ```database.php```. Later changes to the environment
-variable are *not* reflected in the configuration file which must be
-edited directly.
-
-\[<a name="note03">3</a>\]: The environment variable is read the first time the container is
-started and written to the persistent volume (or bind mount) in the 
-configuration file ```email.php```. Later changes to the environment
-variable are *not* reflected in the configuration file which must be
-edited directly.
+\[<a name="note02">2</a>\]: The environment variable is read when the container starts
+and written to the configuration file ```database.php``` if the file does not already
+exist, either because it has been mounted using a persistent volume (or bind mount) or has
+been added when using the image as a base to build a new image.
 
+\[<a name="note03">3</a>\]: The environment variable is read when the container starts
+and written to the configuration file ```email.php``` if the file does not already
+exist, either because it has been mounted using a persistent volume (or bind mount) or has
+been added when using the image as a base to build a new image.