annotate docs/usage/email.rst @ 5770:82f818616265

db: cache SCM instance short-term (tied to SQLAlchemy session lifetime) Repeatedly checking whether SCM instances are invalidated is slow, and we don't actually _want_ SCM instances to invalidate half-way through a request either. Therefore cache them in on the db.Repository object, the lifetime of which is directly tied to the lifetime of the SQLAlchemy session, the lifetime of which is tied directly to the individual HTTP request. This way, we only check for invalidation the first time the SCM instance is accessed in a request. This will improve performance in cases where we have (by definition) badly written code that retrieves repo objects several times.
author Søren Løvborg <sorenl@unity3d.com>
date Tue, 08 Mar 2016 12:28:06 +0100
parents c935bcaf7086
children a5ad2900985b ea9342f8d46b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
1 .. _email:
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
2
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
3 ==============
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
4 Email settings
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
5 ==============
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
6
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
7 The Kallithea configuration file has several email related settings. When
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
8 these contain correct values, Kallithea will send email in the situations
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
9 described below. If the email configuration is not correct so that emails
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
10 cannot be sent, all mails will show up in the log output.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
11
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
12 Before any email can be sent, an SMTP server has to be configured using the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
13 configuration file setting ``smtp_server``. If required for that server, specify
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
14 a username (``smtp_username``) and password (``smtp_password``), a non-standard
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
15 port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
16 and/or specific authentication parameters (``smtp_auth``).
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
17
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
18
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
19 Application emails
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
20 ------------------
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
21
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
22 Kallithea sends an email to `users` on several occasions:
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
23
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
24 - when comments are given on one of their changesets
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
25 - when comments are given on changesets they are reviewer on or on which they
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
26 commented regardless
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
27 - when they are invited as reviewer in pull requests
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
28 - when they request a password reset
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
29
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
30 Kallithea sends an email to all `administrators` upon new account registration.
5426
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
31 Administrators are users with the ``Admin`` flag set on the *Admin > Users*
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
32 page.
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
33
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
34 When Kallithea wants to send an email but due to an error cannot correctly
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
35 determine the intended recipients, the administrators and the addresses
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
36 specified in ``email_to`` in the configuration file are used as fallback.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
37
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
38 Recipients will see these emails originating from the sender specified in the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
39 ``app_email_from`` setting in the configuration file. This setting can either
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
40 contain only an email address, like `kallithea-noreply@example.com`, or both
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
41 a name and an address in the following format: `Kallithea
5455
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
42 <kallithea-noreply@example.com>`. However, if the email is sent due to an
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
43 action of a particular user, for example when a comment is given or a pull
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
44 request created, the name of that user will be combined with the email address
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
45 specified in ``app_email_from`` to form the sender (and any name part in that
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
46 configuration setting disregarded).
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
47
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
48 The subject of these emails can optionally be prefixed with the value of
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
49 ``email_prefix`` in the configuration file.
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
50
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
51
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
52 Error emails
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
53 ------------
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
54
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
55 When an exception occurs in Kallithea -- and unless interactive debugging is
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
56 enabled using ``set debug = true`` in the ``[app:main]`` section of the
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
57 configuration file -- an email with exception details is sent by WebError_'s
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
58 ``ErrorMiddleware`` to the addresses specified in ``email_to`` in the
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
59 configuration file.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
60
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
61 Recipients will see these emails originating from the sender specified in the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
62 ``error_email_from`` setting in the configuration file. This setting can either
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
63 contain only an email address, like `kallithea-noreply@example.com`, or both
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
64 a name and an address in the following format: `Kallithea Errors
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
65 <kallithea-noreply@example.com>`.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
66
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
67 *Note:* The WebError_ package does not respect ``smtp_port`` and assumes the
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
68 standard SMTP port (25). If you have a remote SMTP server with a different port,
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
69 you could set up a local forwarding SMTP server on port 25.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
70
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
71
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
72 References
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
73 ----------
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5412
diff changeset
74
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
75 - `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
76 - `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
77
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
78
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
79 .. _WebError: https://pypi.python.org/pypi/WebError