gitlab-org--gitlab-foss/doc/reply_by_email/postfix.md

# 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
    su - 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 /etc/init.d/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
        su - 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 "inet_interfaces = all"
    ```

1. Configure Postfix to receive mail on both IPv4 and IPv6 protocols:
    
    ```sh
    sudo postconf -e "inet_protocols = all"
    ```

1. Configure Postfix to use the `+` delimiter for sub-addressing:
    
    ```sh
    sudo postconf -e "recipient_delimiter = +"
    ```

1. Restart Postfix:
    
    ```sh
    sudo /etc/init.d/postfix restart
    ```

## 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
        su - 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._