[PATCH] docs: Add getmail documentation

[Daniel Axtens]

LGTM.

Reviewed-by: Daniel Axtens <dja at axtens.net>

Regards,
Daniel

Stephen Finucane <stephen at that.guru> writes:

> It seems a lot of people are having success using tools like fetchmail
> in combination with IMAP/POP-capable email accounts like Gmail.  While
> fetchmail itself is rather decrepit, the Python-based getmail seems
> actively supported and pretty easy to configure. Document this process.
>
> Signed-off-by: Stephen Finucane <stephen at that.guru>
> ---
>  docs/deployment/installation.md | 89 +++++++++++++++++++++++++++++++++--------
>  1 file changed, 72 insertions(+), 17 deletions(-)
>
> diff --git a/docs/deployment/installation.md b/docs/deployment/installation.md
> index 0867daa..3566c7d 100644
> --- a/docs/deployment/installation.md
> +++ b/docs/deployment/installation.md
> @@ -357,16 +357,77 @@ to receive email at. This is a problem that has been solved for many webapps,
>  thus there are many ways to go about this. Some of these ways are discussed
>  below.
>  
> -### Postfix
> +### IMAP/POP3
> +
> +The easiest option for getting mail into Patchwork is to use an existing email
> +address in combination with a mail retriever like [getmail][ref-getmail], which
> +will download mails from your inbox and pass them to Patchwork for processing.
> +getmail is easy to set up and configure: to begin, you need to install it:
> +
> +    $ sudo apt-get install getmail4
> +
> +Once installed, you should configure it, sustituting your own configuration
> +details where required below:
> +
> +    $ sudo cat << EOF > /etc/getmail/user at example.com/getmailrc
> +    [retriever]
> +    type = SimpleIMAPSSLRetriever
> +    server = imap.example.com
> +    port = 993
> +    username = XXX
> +    password = XXX
> +    mailboxes = ALL
> +
> +    [destination]
> +    # we configure Patchwork as a "mail delivery agent", in that it will
> +    # handle our mails
> +    type = MDA_external
> +    path = /opt/patchwork/patchwork/bin/parsemail.sh
> +
> +    [options]
> +    # retrieve only new emails
> +    read_all = false
> +    # do not add a Delivered-To: header field
> +    delivered_to = false
> +    # do not add a Received: header field
> +    received = false
> +    EOF
>  
> -The most flexible option is to configure our own mail transfer agent (MTA) and
> -Postfix is as good a choice as any. While we don't cover setting up Postfix
> -here (it's complicated and there are many guides already available), Patchwork
> -does include a script to take received mails and create the relevant entries
> -in Patchwork for you. To use this, you should configure your system to forward
> -all emails to a given localpart (the bit before the `@`) to this script. Using
> -the `patchwork` localpart (e.g. `patchwork at example.com`) you can do this like
> -so:
> +Validate that this works as expected by starting `getmail`:
> +
> +    $ getmail --getmaildir=/etc/getmail/user at example.com --idle INBOX
> +
> +If everything works as expected, you can create a systemd script to ensure this
> +starts on boot:
> +
> +    $ sudo cat << EOF > /etc/systemd/system/getmail.service
> +    [Unit]
> +    Description=Getmail for user at example.com
> +
> +    [Service]
> +    User=pathwork
> +    ExecStart=/usr/bin/getmail --getmaildir=/etc/getmail/user at example.com --idle INBOX
> +    Restart=always
> +
> +    [Install]
> +    WantedBy=multi-user.target
> +    EOF
> +
> +And start the service:
> +
> +    $ sudo systemctl start getmail
> +    $ sudo systemctl status getmail
> +
> +### Mail Transfer Agent (MTA)
> +
> +The most flexible option is to configure our own mail transfer agent (MTA) or
> +"email server". There are many options, of which [Postfix][ref-postfix] is one.
> +While we don't cover setting up Postfix here (it's complicated and there are
> +many guides already available), Patchwork does include a script to take
> +received mails and create the relevant entries in Patchwork for you. To use
> +this, you should configure your system to forward all emails to a given
> +localpart (the bit before the `@`) to this script. Using the `patchwork`
> +localpart (e.g. `patchwork at example.com`) you can do this like so:
>  
>      $ sudo cat << EOF > /etc/aliases
>      patchwork: "|/opt/patchwork/patchwork/bin/parsemail.sh"
> @@ -386,14 +447,6 @@ change both the username in the `createuser` command above and substitute the
>  username in the `grant-all-postgres.sql` script with the appropriate
>  alternative.
>  
> -### IMAP/POP3
> -
> -One could also use an email account provided by a run-of-the-mill email
> -provider and retrieve mail using IMAP or POP3. This may be suitable for
> -low-volume mailing lists but be warned: this will introduce a significant lag
> -between when a patch is submitted to a mailing list and when it appears in
> -Patchwork.
> -
>  ### Use a Email-as-a-Service Provider
>  
>  Setting up an email server can be a difficult task and, in the case of
> @@ -428,7 +481,9 @@ it.
>  [doc-development]: development.md
>  [ref-django-files]: https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-a-project
>  [ref-django-settings]: https://docs.djangoproject.com/en/1.8/ref/settings/
> +[ref-getmail]: http://pyropus.ca/software/getmail/
>  [ref-pkgs]: http://pkgs.org/
> +[ref-postfix]: http://www.postfix.org/
>  [ref-uwsgi-emperor]: https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
>  [ref-uwsgi-systemd]: https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html
>  [ref-uwsgi-upstart]: https://uwsgi-docs.readthedocs.io/en/latest/Upstart.html
> -- 
> 2.7.4
>
> _______________________________________________
> Patchwork mailing list
> Patchwork at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 859 bytes
Desc: not available
URL: <http://lists.ozlabs.org/pipermail/patchwork/attachments/20161021/601b902c/attachment.sig>