docs/install.md

   1 # Mailpopbox Installation Guide
   2
   3 This guide covers how to install mailpopbox, set up auto-renewing TLS certificates, and setting up
   4 Gmail to POP messages off the server.
   5
   6 ## Server
   7
   8 Installation requires root access on a server capable of running long-lived processes. I recommend
   9 [Digital Ocean droplets](https://www.digitalocean.com/products/droplets/), which cost $5/month. This
  10 guide does not cover how to properly secure a Linux server, such as SSH configuration; please use
  11 other guides to do that if this is a new instance.
  12
  13 ## Install Mailpopbox
  14
  15 These commands assume you are running as root; if not, precede the commands with `sudo`.
  16
  17 1. Download the latest mailpopbox release and copy the binary to `/usr/local/bin`
  18
  19 2. Set ownership and permissions:
  20     - `chown root:wheel /usr/local/bin/mailpopbox`
  21     - `chmod 755 /usr/local/bin/mailpopbox`
  22
  23 3. Create a new user that the server will run under: `useradd mailpopbox --shell /sbin/nologin`
  24
  25 4. Create some directories with the correct permissions:
  26     - `cd /home/mailpopbox`
  27     - `mkdir -p maildrop/yourdomain.com cert www/.well-known/acme-challenge`
  28     - `chown -R mailpopbox:mailpopbox maildrop cert www`
  29
  30 5. Create a file at `/home/mailpopbox/config.json`:
  31
  32     ```
  33     {
  34         "SMTPPort": 9025,
  35         "POP3Port": 9995,
  36         "Hostname": "mx.yourdomain.com",
  37         "Servers": [
  38             {
  39                 "Domain": "yourdomain.com",
  40                 "MailboxPassword": "yourpassword",
  41                 "TLSKeyPath": "/home/mailpopbox/cert/certificates/mx.yourdomain.com.key",
  42                 "TLSCertPath": "/home/mailpopbox/cert/certificates/mx.yourdomain.com.crt",
  43                 "MaildropPath": "/home/mailpopbox/maildrop/yourdomain.com"
  44             }
  45         ]
  46     }
  47     ```
  48
  49     - The SMTP and POP3 ports are not the values that will be exposed to the Internet, as those are
  50         reserved ports that require root access to bind. Instead, mailpopbox binds these
  51         unprivileged ports and *iptables* will be used to route Internet traffic to the server. This
  52         is handled by the included systemd unit.
  53     - The `Hostname` is the MX server hostname. Multiple catch-all domains can be configured, but
  54         they will all share this MX hostname in e.g. the SMTP HELO.
  55     - The `Domain` is the domain name for which `*@yourdomain.com` will be set up.
  56     - The `MailboxPassword` is the password for the `mailbox@yourdomain.com` account, used to
  57         authenticate POP3 and outbound SMTP connections. Choose a strong password!
  58     - The `TLSKeyPath` and `TLSCertPath` are used to find the TLS certificate, which will be
  59         configured below.
  60     - The `MaildropPath` is where delivered messages are stored until they are POP'd off the
  61         server.
  62
  63 ## Setup Automatic TLS Certificates
  64
  65 This guide will assume that your instance of mailpopbox is running on a system that also has a
  66 web server running. The web server will be used to host [ACME
  67 certificate](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment) challenges.
  68 I recommend the [lego](https://github.com/go-acme/lego) tool for certificate management. If you
  69 already have a mechanism to get certificates, you can use that and just adjust the paths in
  70 `config.json`.
  71
  72 1. Install [lego](https://github.com/go-acme/lego) on the server.
  73
  74 2. Configure your web server to serve the content under the mailpopbox home directory. With an
  75 apache2 configuration, this can be done by editing `/etc/httpd/conf.d/mx.yourdomain.com` with this
  76 content:
  77
  78     ```
  79     <VirtualHost *:80>
  80         ServerName mx.yourdomain.com
  81
  82         ErrorLog logs/yourdomain_error_log
  83         CustomLog logs/yourdomain_access_log combined
  84
  85         DocumentRoot /home/mailpopbox/www
  86     </VirtualHost>
  87
  88     <Directory /home/mailpopbox/www>
  89         Require all granted
  90     </Directory>
  91     ```
  92
  93 3. Reload the web server `systemctl reload httpd.service`
  94
  95 4. Customize this command and register for the initial account and certificate:
  96
  97         sudo -u mailpopbox /usr/local/bin/lego --email email@domain.com --domains mx.yourdomain.com --http --http.webroot /home/mailpopbox/www --path /home/mailpopbox/cert run
  98
  99   This will register *email@domain.com* with [LetsEncrypt](https://letsencrypt.org) to get a
 100   certificate for *mx.yourdomain.com* by putting an authentication challenge file in the
 101   `/home/mailpopbox/www` directory, with the resulting certificate files in `/home/mailpopbox/cert`.
 102
 103
 104 5. Let mailpopbox restart itself via systemd by editing the sudoers file with `visudo`, and add this
 105 line:
 106
 107         mailpopbox ALL=(root) NOPASSWD: /usr/bin/systemctl restart mailpopbox.service
 108
 109 6. Set up a cron job to automatically renew the certificate using `sudo crontab -u mailpopbx -e`
 110 and specifying this command (which is nearly the same as the `run` above, except it uses `renew` and
 111 a hook). Customize this command:
 112
 113         0 22 * * * /usr/local/bin/lego --email email@domain.com --domains mx.yourdomain.com --http --http.webroot /home/mailpopbox/www --path /home/mailpopbox/cert renew --renew-hook "sudo /usr/bin/systemctl restart mailpopbox.service"
 114
 115 ## Configure DNS
 116
 117 1. Add a DNS A record to `yourdomain.com`, to set up `mx.yourdomain.com` to point to the public IP
 118 address of the server running mailpopbox.
 119
 120 2. Set or change the DNS MX record of `yourdomain.com` to point to `mx.yourdomain.com`.
 121
 122 Changes to DNS can take up between 1 and 24 hours to propagate.
 123
 124 ## Starting Mailpopbox
 125
 126 1. Copy the `mailpopbox.service` systemd unit file from the release archive to
 127 `/usr/local/lib/systemd/system`
 128
 129 > Note that the systemd unit file uses `/sbin/iptables` to forward traffic from ports 25 and 995 to
 130 > the ports specified in the `config.json` file. It also specifies the path to the `config.json`
 131 > file.
 132
 133 2. Enable the systemd unit with `systemctl enable mailpopbox.service`
 134
 135 3. Start mailpopbox with `systemctl start mailpopbox.service`
 136
 137 4. Verify that the server has started with `journalctl -u mailpopbox`
 138
 139 5. Test the connection to the server from your local machine: `openssl s_client -connect
 140 mx.yourdomain.com:995`. You should see your certificate printed by `openssl` and then a line that
 141 says `+OK POP3 (mailpopbox) server mx.yourdomain.com`.
 142
 143 ## Configuring Your Email Client
 144
 145 Now that mailpopbox is running and DNS is configured, it is time to set your mail client up to
 146 connect to it. We will set up both a POP3 account to download delivered mail, and a SMTP account to
 147 enable replying. This guide is for Gmail, but the configuration parameters are the same regardless
 148 of client.
 149
 150 1. Go to **Gmail Settings** > **Accounts and Import**
 151
 152 2. Under **Check mail from other accounts:**, click **Add a mail account**
 153
 154 3. Specify `mailbox@yourdomain.com` as the email address and click **Next**
 155
 156 4. Choose **Import emails from my other account (POP3)** and click **Next**
 157
 158 5. Specify the following configuration and add the account:
 159     - **Username:** `mailbox@yourdomain.com`
 160     - **Password:** The password you specified in `config.json`
 161     - **POP Server:** `mx.yourdomain.com`
 162     - **Port:** `995`
 163     - Check **Always use a secure connection (SSL) when retrieving mail**
 164     - Optionally, apply a label to all the messages sent to this domain
 165
 166 Gmail will now fetch messages delivered to the server. You can send a test message to
 167 `install-test@yourdomain.com` and it should be delivered within a few minutes. Note that Gmail
 168 fetches mail from the POP account periodically via polling, so message delivery can seem slower than
 169 normal.
 170
 171 1. Go to **Gmail Settings** > **Accounts and Import**
 172
 173 2. Under **Send mail as:**, click **Add another email address**
 174
 175 3. Specify the following and click **Next**:
 176     - **Name:** Whatever you prefer
 177     - **Email:** `mailbox@yourdomain.com`
 178     - Check **Treat as an alias**
 179
 180 4. Specify the following and add the account:
 181     - **SMTP Server:** `mx.yourdomain.com`
 182     - **Port:** `25`
 183     - **Username:** `mailbox@yourdomain.com`
 184     - **Password:** The password you specified in `config.json`
 185     - Check **Secured connection using TLS**
 186
 187 Gmail will now let you send email as *mailbox@yourdomain.com*. But if you are replying to a message
 188 sent to *random@yourdomain.com*, you do not want the recipient to see the "mailbox" username in your
 189 reply. If you append `[sendas:random]` to the Subject line of the message, the SMTP server will
 190 change the From address to `random@yourdomain.com` and remove the special tag from the Subject line.