Expand documentation
This commit is contained in:
Douwe Maan
parent
a2f170b35a
commit
7d5c6a1ada
|
|
@ -2,11 +2,13 @@
|
|||
|
||||
GitLab can be set up to allow users to comment on issues and merge requests by replying to notification emails.
|
||||
|
||||
In order to do this, you need access to an IMAP-enabled email account, with a provider or server that supports [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing). Sub-addressing is a feature where any email to `user+some_arbitrary_tag@example.com` will end up in the mailbox for `user@example.com`, and is supported by providers such as Gmail, Yahoo! Mail, Outlook.com and iCloud, as well as the [Postfix](http://www.postfix.org/) mail server which you can run on-premises.
|
||||
## Get a mailbox
|
||||
|
||||
If you want to use a Gmail with Reply by email, make sure you have [IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) and [allow less secure apps to access the account](https://support.google.com/accounts/answer/6010255).
|
||||
Reply by email requires an IMAP-enabled email account, with a provider or server that supports [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing). Sub-addressing is a feature where any email to `user+some_arbitrary_tag@example.com` will end up in the mailbox for `user@example.com`, and is supported by providers such as Gmail, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix mail server which you can run on-premises.
|
||||
|
||||
To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these instructions](https://help.ubuntu.com/community/PostfixBasicSetupHowto).
|
||||
If you want to use Gmail with Reply by email, make sure you have [IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) and [allow less secure apps to access the account](https://support.google.com/accounts/answer/6010255).
|
||||
|
||||
To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these instructions](./postfix.md).
|
||||
|
||||
## Set it up
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,316 @@
|
|||
# Set up Postfix for Reply by email
|
||||
|
||||
This document will take you through the steps of setting up a basic Postfix mail server with IMAP authentication on Ubuntu, to be used with Reply by email.
|
||||
|
||||
The instructions make the assumption that you will be using the email address `replies@gitlab.example.com`, that is, username `replies` on host `gitlab.example.com`. Don't forget to change it to your actual host when executing the example code snippets.
|
||||
|
||||
## Configure your server DNS
|
||||
|
||||
1. Add an MX record pointing from `gitlab.example.com` to your server IP.
|
||||
1. Add an A record pointing from `mail.gitlab.example.com` to your server IP.
|
||||
1. Verify that the changes have propagated:
|
||||
|
||||
```sh
|
||||
dig mx gitlab.example.com
|
||||
```
|
||||
|
||||
```sh
|
||||
dig a mail.gitlab.example.com
|
||||
```
|
||||
|
||||
You should see an `ANSWER SECTION` with the expected result in the output for both.
|
||||
|
||||
## Install packages
|
||||
|
||||
1. Install the `postfix` package if it is not installed already:
|
||||
|
||||
```sh
|
||||
sudo apt-get install postfix
|
||||
```
|
||||
|
||||
When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`.
|
||||
|
||||
1. Install the `mailutils` package.
|
||||
|
||||
```sh
|
||||
sudo apt-get install mailutils
|
||||
```
|
||||
|
||||
## Create user
|
||||
|
||||
1. Create a user for replies.
|
||||
|
||||
```sh
|
||||
sudo useradd -m -s /bin/bash replies
|
||||
```
|
||||
|
||||
1. Set a password for this user.
|
||||
|
||||
```sh
|
||||
sudo passwd replies
|
||||
```
|
||||
|
||||
Be sure not to forget this, you'll need it later.
|
||||
|
||||
## Test the out-of-the-box setup
|
||||
|
||||
1. Connect to the local SMTP server:
|
||||
|
||||
```sh
|
||||
telnet localhost 25
|
||||
```
|
||||
|
||||
You should see a prompt like this:
|
||||
|
||||
```sh
|
||||
Trying 127.0.0.1...
|
||||
Connected to localhost.
|
||||
Escape character is '^]'.
|
||||
220 gitlab.example.com ESMTP Postfix (Ubuntu)
|
||||
```
|
||||
|
||||
If you get a `Connection refused` error instead, check if `postfix` is running:
|
||||
|
||||
```sh
|
||||
sudo postfix status
|
||||
```
|
||||
|
||||
If it is not, start it:
|
||||
|
||||
```sh
|
||||
sudo postfix start
|
||||
```
|
||||
|
||||
1. Send the new `replies` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
|
||||
|
||||
```
|
||||
ehlo localhost
|
||||
mail from: root@localhost
|
||||
rcpt to: replies@localhost
|
||||
data
|
||||
Subject: Re: Some issue
|
||||
|
||||
Sounds good!
|
||||
.
|
||||
quit
|
||||
```
|
||||
|
||||
(Note: The `.` is a literal period on its own line)
|
||||
|
||||
1. Check if the `replies` user received the email:
|
||||
|
||||
```sh
|
||||
sh - replies
|
||||
mail
|
||||
```
|
||||
|
||||
You should see output like this:
|
||||
|
||||
```
|
||||
"/var/mail/replies": 1 message 1 unread
|
||||
>U 1 root@localhost 59/2842 Re: Some issue
|
||||
```
|
||||
|
||||
Quit the mail app:
|
||||
|
||||
```sh
|
||||
q
|
||||
```
|
||||
|
||||
1. Log out of the `replies` account and go back to being `root`:
|
||||
|
||||
```sh
|
||||
logout
|
||||
```
|
||||
|
||||
## Configure Postfix to use Maildir-style mailboxes
|
||||
|
||||
Courier, which we will install later to add IMAP authentication, requiers mailboxes to have the Maildir format, rather than mbox.
|
||||
|
||||
1. Configure Postfix to use Maildir-style mailboxes:
|
||||
|
||||
```sh
|
||||
sudo postconf -e "home_mailbox = Maildir/"
|
||||
sudo postconf -e "mailbox_command = "
|
||||
```
|
||||
|
||||
1. Restart Postfix:
|
||||
|
||||
```sh
|
||||
sudo postfix restart
|
||||
```
|
||||
|
||||
1. Test the new setup:
|
||||
|
||||
1. Follow steps 1 and 2 of "Test the out-of-the-box setup".
|
||||
2. Check if the `replies` user received the email:
|
||||
|
||||
```sh
|
||||
sh - replies
|
||||
MAIL=/home/replies/Maildir
|
||||
mail
|
||||
```
|
||||
|
||||
You should see output like this:
|
||||
|
||||
```
|
||||
"/home/replies/Maildir": 1 message 1 unread
|
||||
>U 1 root@localhost 59/2842 Re: Some issue
|
||||
```
|
||||
|
||||
Quit the mail app:
|
||||
|
||||
```sh
|
||||
q
|
||||
```
|
||||
|
||||
1. Log out of the `replies` account and go back to being `root`:
|
||||
|
||||
```sh
|
||||
logout
|
||||
```
|
||||
|
||||
## Install the Courier IMAP server
|
||||
|
||||
1. Install the `courier-imap` package:
|
||||
|
||||
```sh
|
||||
sudo apt-get install courier-imap
|
||||
```
|
||||
|
||||
## Configure Postfix to receive email from the internet
|
||||
|
||||
1. Let Postfix know about the domains that it should consider local:
|
||||
|
||||
```sh
|
||||
sudo postconf -e "mydestination = mail.gitlab.example.com, localhost.localdomain, localhost, gitlab.example.com"
|
||||
```
|
||||
|
||||
1. Let Postfix know about the IPs that it should consider part of the LAN:
|
||||
|
||||
We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
|
||||
|
||||
```sh
|
||||
sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
|
||||
```
|
||||
|
||||
1. Configure Postfix to receive mail on all interfaces, which includes the internet:
|
||||
|
||||
```sh
|
||||
sudo postconf -e "init_interfaces = all"
|
||||
```
|
||||
|
||||
1. Configure Postfix to receive mail on both IPv4 and IPv6 protocols:
|
||||
|
||||
```sh
|
||||
sudo postconf -e "inet_protocols = all"
|
||||
```
|
||||
|
||||
## Test the final setup
|
||||
|
||||
1. Test SMTP under the new setup:
|
||||
|
||||
1. Connect to the SMTP server:
|
||||
|
||||
```sh
|
||||
telnet mail.gitlab.example.com 25
|
||||
```
|
||||
|
||||
You should see a prompt like this:
|
||||
|
||||
```sh
|
||||
Trying 123.123.123.123...
|
||||
Connected to mail.gitlab.example.com.
|
||||
Escape character is '^]'.
|
||||
220 gitlab.example.com ESMTP Postfix (Ubuntu)
|
||||
```
|
||||
|
||||
If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25.
|
||||
|
||||
1. Send the `replies` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
|
||||
|
||||
```
|
||||
ehlo gitlab.example.com
|
||||
mail from: root@gitlab.example.com
|
||||
rcpt to: replies@gitlab.example.com
|
||||
data
|
||||
Subject: Re: Some issue
|
||||
|
||||
Sounds good!
|
||||
.
|
||||
quit
|
||||
```
|
||||
|
||||
(Note: The `.` is a literal period on its own line)
|
||||
|
||||
1. Check if the `replies` user received the email:
|
||||
|
||||
```sh
|
||||
sh - replies
|
||||
MAIL=/home/replies/Maildir
|
||||
mail
|
||||
```
|
||||
|
||||
You should see output like this:
|
||||
|
||||
```
|
||||
"/home/replies/Maildir": 1 message 1 unread
|
||||
>U 1 root@gitlab.example.com 59/2842 Re: Some issue
|
||||
```
|
||||
|
||||
Quit the mail app:
|
||||
|
||||
```sh
|
||||
q
|
||||
```
|
||||
|
||||
1. Log out of the `replies` account and go back to being `root`:
|
||||
|
||||
```sh
|
||||
logout
|
||||
```
|
||||
|
||||
1. Test IMAP under the new setup:
|
||||
|
||||
1. Connect to the IMAP server:
|
||||
|
||||
```sh
|
||||
telnet mail.gitlab.example.com 143
|
||||
```
|
||||
|
||||
You should see a prompt like this:
|
||||
|
||||
```sh
|
||||
Trying 123.123.123.123...
|
||||
Connected to mail.example.gitlab.com.
|
||||
Escape character is '^]'.
|
||||
- OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information.
|
||||
```
|
||||
|
||||
1. Sign in as the `replies` user to test IMAP, by entering the following into the IMAP prompt:
|
||||
|
||||
```
|
||||
a login replies PASSWORD
|
||||
```
|
||||
|
||||
Replace PASSWORD by the password you set on the `replies` user earlier.
|
||||
|
||||
You should see output like this:
|
||||
|
||||
```
|
||||
a OK LOGIN Ok.
|
||||
```
|
||||
|
||||
1. Disconnect from the IMAP server:
|
||||
|
||||
```sh
|
||||
a logout
|
||||
```
|
||||
|
||||
## Done!
|
||||
|
||||
If all the tests went all right, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) doc to configure GitLab.
|
||||
|
||||
---------
|
||||
|
||||
_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._
|
||||
Loading…
Reference in New Issue