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