[PATCH 6 of 6] e-mail: add documentation about configuration settings
Thomas De Schampheleire
patrickdepinguin at gmail.com
Sun Aug 2 20:51:40 UTC 2015
# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
# Date 1437061235 -7200
# Thu Jul 16 17:40:35 2015 +0200
# Node ID b6ead0eb65812005d1b5a5893f54efb1f08ee079
# Parent b2edf3d7ad971e48214632bba5187c490161716d
e-mail: add documentation about configuration settings
Document e-mail related configuration settings in the documentation
(overview) and the .ini file itself (technical details and example
settings).
This includes a replacement of @localhost examples to @example.com, to
indicate that real addresses should normally be used.
diff --git a/development.ini b/development.ini
--- a/development.ini
+++ b/development.ini
@@ -16,16 +16,37 @@ debug = true
pdebug = false
################################################################################
-## Uncomment and replace with the address which should receive ##
-## any error reports after application crash ##
-## Additionally those settings will be used by Kallithea mailing system ##
+## E-mail settings ##
+## ##
+## Refer to the documentation ("E-mail settings") for more details. ##
+## ##
+## It is recommended to use a valid sender address that passes access ##
+## validation and spam filtering in mail servers. ##
################################################################################
-#email_to = admin at localhost
-#error_email_from = paste_error at localhost
-#error_subject_prefix =
-#app_email_from = kallithea-noreply at localhost
+
+## From header for application e-mails. You can optionally add a name. Examples:
+#app_email_from = Kallithea <kallithea-noreply at example.com>
+#app_email_from = kallithea-noreply at example.com
+
+## Subject prefix for application e-mails.
+## A space between this prefix and the real subject is automatically added.
+## Example:
#email_prefix = [Kallithea]
+## Recipients for error e-mails and fallback recipients of application mails.
+## Multiple addresses can be specified, space-separated.
+## Only addresses are allowed, do not add any name part.
+#email_to = admin at example.com
+
+## From header for error e-mails. You can optionally add a name. Examples:
+#error_email_from = Kallithea Errors <kallithea-noreply at example.com>
+#error_email_from = paste_error at example.com
+
+## Subject prefix for error e-mails.
+## Standard trailing spaces are trimmed, use a Unicode variant like U+2002
+## instead. For example (there is a trailing U+2002 space after ]):
+#error_subject_prefix = [Kallithea error]
+
#smtp_server = mail.server.com
#smtp_username =
#smtp_password =
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ Kallithea Documentation
.. toctree::
:maxdepth: 1
+ usage/e-mail
usage/performance
usage/backup
usage/debugging
diff --git a/docs/usage/e-mail.rst b/docs/usage/e-mail.rst
new file mode 100644
--- /dev/null
+++ b/docs/usage/e-mail.rst
@@ -0,0 +1,61 @@
+.. _email:
+
+===============
+E-mail settings
+===============
+
+The Kallithea configuration file has several e-mail related settings. When these
+contain correct values, Kallithea will send e-mail in the situations described
+below.
+
+Application e-mails
+-------------------
+
+Kallithea sends an e-mail to `users` on several occasions:
+
+- when comments are given on one of their changesets
+- when comments are given on changesets they also commented on
+- when they are invited as reviewer in pull requests
+- when they request a password reset
+
+Kallithea sends an e-mail to all `administrators` upon new account registration.
+Administrators are users with the ``Admin`` flag set in the ``Admin->Users``
+section.
+
+In case Kallithea tries to send an e-mail to unspecified recipients, the
+administrators and the addresses specified in ``email_to`` in the configuration
+file are used as fallback.
+
+The ``From`` header of these e-mails is set using the ``app_email_from`` setting
+in the configuration file. The ``Subject`` of these e-mails can optionally be
+prefixed with the value of ``email_prefix`` in the configuration file.
+
+Error e-mails
+-------------
+
+When an exception occurs in Kallithea -- and unless interactive debugging is
+enabled using ``set debug = true`` in the ``[app:main]`` section of the
+configuration file -- an e-mail with exception details is sent by WebError_'s
+``ErrorMiddleware`` to the addresses specified in ``email_to`` in the
+configuration file.
+
+The ``From`` header of these e-mails is set using the ``error_email_from``
+setting in the configuration file. The ``Subject`` of these e-mails can
+optionally be prefixed with the value of ``error_subject_prefix`` in the
+configuration file. This value defaults to '`WebApp Error:` '.
+
+_Note:_ Due to the way configuration files are parsed, trailing whitespace is
+ignored. For ``error_subject_prefix``, however, a trailing space can be
+desirable. A simple solution is to add a special Unicode space instead, for
+example `U+2002 (EN SPACE)`: ' '.
+
+_Note:_ The WebError_ package does not respect ``smtp_port`` and assumes the
+standard SMTP port (25). If you have a remote SMTP server with a different port,
+you could set up a local forwarding SMTP server on port 25.
+
+References
+----------
+- `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_
+- `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_
+
+.. _WebError: https://pypi.python.org/pypi/WebError
diff --git a/kallithea/bin/template.ini.mako b/kallithea/bin/template.ini.mako
--- a/kallithea/bin/template.ini.mako
+++ b/kallithea/bin/template.ini.mako
@@ -10,16 +10,37 @@ debug = true
pdebug = false
<%text>
################################################################################
-## Uncomment and replace with the address which should receive ##
-## any error reports after application crash ##
-## Additionally those settings will be used by Kallithea mailing system ##
+## E-mail settings ##
+## ##
+## Refer to the documentation ("E-mail settings") for more details. ##
+## ##
+## It is recommended to use a valid sender address that passes access ##
+## validation and spam filtering in mail servers. ##
################################################################################</%text>
-#email_to = admin at localhost
-#error_email_from = paste_error at localhost
-#error_subject_prefix =
-#app_email_from = kallithea-noreply at localhost
+
+<%text>## From header for application e-mails. You can optionally add a name. Examples:</%text>
+#app_email_from = Kallithea <kallithea-noreply at example.com>
+#app_email_from = kallithea-noreply at example.com
+
+<%text>## Subject prefix for application e-mails.
+## A space between this prefix and the real subject is automatically added.
+## Example:</%text>
#email_prefix = [Kallithea]
+<%text>## Recipients for error e-mails and fallback recipients of application mails.
+## Multiple addresses can be specified, space-separated.
+## Only addresses are allowed, do not add any name part.</%text>
+#email_to = admin at example.com
+
+<%text>## From header for error e-mails. You can optionally add a name. Examples:</%text>
+#error_email_from = Kallithea Errors <kallithea-noreply at example.com>
+#error_email_from = paste_error at example.com
+
+<%text>## Subject prefix for error e-mails.
+## Standard trailing spaces are trimmed, use a Unicode variant like U+2002
+## instead. For example (there is a trailing U+2002 space after ]):</%text>
+#error_subject_prefix = [Kallithea error]
+
#smtp_server = mail.server.com
#smtp_username =
#smtp_password =
diff --git a/kallithea/config/deployment.ini_tmpl b/kallithea/config/deployment.ini_tmpl
--- a/kallithea/config/deployment.ini_tmpl
+++ b/kallithea/config/deployment.ini_tmpl
@@ -11,16 +11,37 @@ debug = true
pdebug = false
################################################################################
-## Uncomment and replace with the address which should receive ##
-## any error reports after application crash ##
-## Additionally those settings will be used by Kallithea mailing system ##
+## E-mail settings ##
+## ##
+## Refer to the documentation ("E-mail settings") for more details. ##
+## ##
+## It is recommended to use a valid sender address that passes access ##
+## validation and spam filtering in mail servers. ##
################################################################################
-#email_to = admin at localhost
-#error_email_from = paste_error at localhost
-#error_subject_prefix =
-#app_email_from = kallithea-noreply at localhost
+
+## From header for application e-mails. You can optionally add a name. Examples:
+#app_email_from = Kallithea <kallithea-noreply at example.com>
+#app_email_from = kallithea-noreply at example.com
+
+## Subject prefix for application e-mails.
+## A space between this prefix and the real subject is automatically added.
+## Example:
#email_prefix = [Kallithea]
+## Recipients for error e-mails and fallback recipients of application mails.
+## Multiple addresses can be specified, space-separated.
+## Only addresses are allowed, do not add any name part.
+#email_to = admin at example.com
+
+## From header for error e-mails. You can optionally add a name. Examples:
+#error_email_from = Kallithea Errors <kallithea-noreply at example.com>
+#error_email_from = paste_error at example.com
+
+## Subject prefix for error e-mails.
+## Standard trailing spaces are trimmed, use a Unicode variant like U+2002
+## instead. For example (there is a trailing U+2002 space after ]):
+#error_subject_prefix = [Kallithea error]
+
#smtp_server = mail.server.com
#smtp_username =
#smtp_password =
diff --git a/test.ini b/test.ini
--- a/test.ini
+++ b/test.ini
@@ -15,16 +15,37 @@ debug = true
pdebug = false
################################################################################
-## Uncomment and replace with the address which should receive ##
-## any error reports after application crash ##
-## Additionally those settings will be used by Kallithea mailing system ##
+## E-mail settings ##
+## ##
+## Refer to the documentation ("E-mail settings") for more details. ##
+## ##
+## It is recommended to use a valid sender address that passes access ##
+## validation and spam filtering in mail servers. ##
################################################################################
-#email_to = admin at localhost
-#error_email_from = paste_error at localhost
-#error_subject_prefix =
-#app_email_from = kallithea-noreply at localhost
+
+## From header for application e-mails. You can optionally add a name. Examples:
+#app_email_from = Kallithea <kallithea-noreply at example.com>
+#app_email_from = kallithea-noreply at example.com
+
+## Subject prefix for application e-mails.
+## A space between this prefix and the real subject is automatically added.
+## Example:
#email_prefix = [Kallithea]
+## Recipients for error e-mails and fallback recipients of application mails.
+## Multiple addresses can be specified, space-separated.
+## Only addresses are allowed, do not add any name part.
+#email_to = admin at example.com
+
+## From header for error e-mails. You can optionally add a name. Examples:
+#error_email_from = Kallithea Errors <kallithea-noreply at example.com>
+#error_email_from = paste_error at example.com
+
+## Subject prefix for error e-mails.
+## Standard trailing spaces are trimmed, use a Unicode variant like U+2002
+## instead. For example (there is a trailing U+2002 space after ]):
+#error_subject_prefix = [Kallithea error]
+
#smtp_server = mail.server.com
#smtp_username =
#smtp_password =
More information about the kallithea-general
mailing list