Mercurial > kallithea
changeset 5366:ce72c36f7a0e
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).
| author | Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> |
|---|---|
| date | Thu, 16 Jul 2015 17:40:35 +0200 |
| parents | ef64905223f5 |
| children | 2d90502bfb63 |
| files | development.ini docs/index.rst docs/usage/e-mail.rst kallithea/bin/template.ini.mako kallithea/config/deployment.ini_tmpl test.ini |
| diffstat | 6 files changed, 190 insertions(+), 20 deletions(-) [+] |
line wrap: on
line diff
--- a/development.ini Thu Jul 16 17:40:35 2015 +0200 +++ b/development.ini Thu Jul 16 17:40:35 2015 +0200 @@ -16,30 +16,55 @@ 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. ## ################################################################################ + +## 'From' header for application e-mails. You can optionally add a name. +## Default: #app_email_from = Kallithea +## Examples: #app_email_from = Kallithea <kallithea-noreply@example.com> #app_email_from = kallithea-noreply@example.com + +## Subject prefix for application e-mails. +## A space between this prefix and the real subject is automatically added. +## Default: #email_prefix = +## Example: #email_prefix = [Kallithea] -#email_to = admin@localhost +## 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. +## Default: +#email_to = +## Examples: #email_to = admin@example.com #email_to = admin@example.com another_admin@example.com + +## 'From' header for error e-mails. You can optionally add a name. +## Default: #error_email_from = pylons@yourapp.com +## Examples: #error_email_from = Kallithea Errors <kallithea-noreply@example.com> #error_email_from = paste_error@example.com +## SMTP server settings +## Only smtp_server is mandatory. All other settings take the specified default +## values. #smtp_server = mail.server.com #smtp_username = #smtp_password = #smtp_port = 25 #smtp_use_tls = false #smtp_use_ssl = false -## Specify available auth parameters here (e.g. LOGIN PLAIN CRAM-MD5, etc.) +## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.). +## If empty, use any of the authentication parameters supported by the server. #smtp_auth = [server:main]
--- a/docs/index.rst Thu Jul 16 17:40:35 2015 +0200 +++ b/docs/index.rst Thu Jul 16 17:40:35 2015 +0200 @@ -37,6 +37,7 @@ .. toctree:: :maxdepth: 1 + usage/e-mail usage/performance usage/backup usage/debugging
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/usage/e-mail.rst Thu Jul 16 17:40:35 2015 +0200 @@ -0,0 +1,69 @@ +.. _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. If the e-mail configuration is not correct so that e-mails +cannot be sent, all mails will show up in the log output. + +Before any e-mail can be sent, an SMTP server has to be configured using the +configuration file setting ``smtp_server``. If required for that server, specify +a username (``smtp_username``) and password (``smtp_password``), a non-standard +port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``) +and/or specific authentication parameters (``smtp_auth``). + +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 are reviewer on or on which they + commented regardless +- 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. + +When Kallithea wants to send an e-mail but due to an error cannot correctly +determine the intended recipients, the administrators and the addresses +specified in ``email_to`` in the configuration file are used as fallback. + +Recipients will see these e-mails originating from the sender specified in the +``app_email_from`` setting in the configuration file. This setting can either +contain only an e-mail address, like `kallithea-noreply@example.com`, or both +a name and an address in the following format: `Kallithea +<kallithea-noreply@example.com>`. 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. + +Recipients will see these e-mails originating from the sender specified in the +``error_email_from`` setting in the configuration file. This setting can either +contain only an e-mail address, like `kallithea-noreply@example.com`, or both +a name and an address in the following format: `Kallithea Errors +<kallithea-noreply@example.com>`. + +*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
--- a/kallithea/bin/template.ini.mako Thu Jul 16 17:40:35 2015 +0200 +++ b/kallithea/bin/template.ini.mako Thu Jul 16 17:40:35 2015 +0200 @@ -10,30 +10,55 @@ pdebug = false <%text>################################################################################</%text> -<%text>## Uncomment and replace with the address which should receive ##</%text> -<%text>## any error reports after application crash ##</%text> -<%text>## Additionally those settings will be used by Kallithea mailing system ##</%text> +<%text>## E-mail settings ##</%text> +<%text>## ##</%text> +<%text>## Refer to the documentation ("E-mail settings") for more details. ##</%text> +<%text>## ##</%text> +<%text>## It is recommended to use a valid sender address that passes access ##</%text> +<%text>## validation and spam filtering in mail servers. ##</%text> <%text>################################################################################</%text> + +<%text>## 'From' header for application e-mails. You can optionally add a name.</%text> +<%text>## Default:</%text> #app_email_from = Kallithea +<%text>## Examples:</%text> #app_email_from = Kallithea <kallithea-noreply@example.com> #app_email_from = kallithea-noreply@example.com + +<%text>## Subject prefix for application e-mails.</%text> +<%text>## A space between this prefix and the real subject is automatically added.</%text> +<%text>## Default:</%text> #email_prefix = +<%text>## Example:</%text> #email_prefix = [Kallithea] -#email_to = admin@localhost +<%text>## Recipients for error e-mails and fallback recipients of application mails.</%text> +<%text>## Multiple addresses can be specified, space-separated.</%text> +<%text>## Only addresses are allowed, do not add any name part.</%text> +<%text>## Default:</%text> +#email_to = +<%text>## Examples:</%text> #email_to = admin@example.com #email_to = admin@example.com another_admin@example.com + +<%text>## 'From' header for error e-mails. You can optionally add a name.</%text> +<%text>## Default:</%text> #error_email_from = pylons@yourapp.com +<%text>## Examples:</%text> #error_email_from = Kallithea Errors <kallithea-noreply@example.com> #error_email_from = paste_error@example.com +<%text>## SMTP server settings</%text> +<%text>## Only smtp_server is mandatory. All other settings take the specified default</%text> +<%text>## values.</%text> #smtp_server = mail.server.com #smtp_username = #smtp_password = #smtp_port = 25 #smtp_use_tls = false #smtp_use_ssl = false -<%text>## Specify available auth parameters here (e.g. LOGIN PLAIN CRAM-MD5, etc.)</%text> +<%text>## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).</%text> +<%text>## If empty, use any of the authentication parameters supported by the server.</%text> #smtp_auth = [server:main]
--- a/kallithea/config/deployment.ini_tmpl Thu Jul 16 17:40:35 2015 +0200 +++ b/kallithea/config/deployment.ini_tmpl Thu Jul 16 17:40:35 2015 +0200 @@ -11,30 +11,55 @@ 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. ## ################################################################################ + +## 'From' header for application e-mails. You can optionally add a name. +## Default: #app_email_from = Kallithea +## Examples: #app_email_from = Kallithea <kallithea-noreply@example.com> #app_email_from = kallithea-noreply@example.com + +## Subject prefix for application e-mails. +## A space between this prefix and the real subject is automatically added. +## Default: #email_prefix = +## Example: #email_prefix = [Kallithea] -#email_to = admin@localhost +## 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. +## Default: +#email_to = +## Examples: #email_to = admin@example.com #email_to = admin@example.com another_admin@example.com + +## 'From' header for error e-mails. You can optionally add a name. +## Default: #error_email_from = pylons@yourapp.com +## Examples: #error_email_from = Kallithea Errors <kallithea-noreply@example.com> #error_email_from = paste_error@example.com +## SMTP server settings +## Only smtp_server is mandatory. All other settings take the specified default +## values. #smtp_server = mail.server.com #smtp_username = #smtp_password = #smtp_port = 25 #smtp_use_tls = false #smtp_use_ssl = false -## Specify available auth parameters here (e.g. LOGIN PLAIN CRAM-MD5, etc.) +## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.). +## If empty, use any of the authentication parameters supported by the server. #smtp_auth = [server:main]
--- a/test.ini Thu Jul 16 17:40:35 2015 +0200 +++ b/test.ini Thu Jul 16 17:40:35 2015 +0200 @@ -15,30 +15,55 @@ 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. ## ################################################################################ + +## 'From' header for application e-mails. You can optionally add a name. +## Default: #app_email_from = Kallithea +## Examples: #app_email_from = Kallithea <kallithea-noreply@example.com> #app_email_from = kallithea-noreply@example.com + +## Subject prefix for application e-mails. +## A space between this prefix and the real subject is automatically added. +## Default: #email_prefix = +## Example: #email_prefix = [Kallithea] -#email_to = admin@localhost +## 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. +## Default: +#email_to = +## Examples: #email_to = admin@example.com #email_to = admin@example.com another_admin@example.com + +## 'From' header for error e-mails. You can optionally add a name. +## Default: #error_email_from = pylons@yourapp.com +## Examples: #error_email_from = Kallithea Errors <kallithea-noreply@example.com> #error_email_from = paste_error@example.com +## SMTP server settings +## Only smtp_server is mandatory. All other settings take the specified default +## values. #smtp_server = mail.server.com #smtp_username = #smtp_password = #smtp_port = 25 #smtp_use_tls = false #smtp_use_ssl = false -## Specify available auth parameters here (e.g. LOGIN PLAIN CRAM-MD5, etc.) +## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.). +## If empty, use any of the authentication parameters supported by the server. #smtp_auth = [server:main]