How To Install Mailpile on Ubuntu 14.04

Introduction

In this tutorial, we will install Mailpile, a fast, secure, and beautiful webmail client, on Ubuntu 14.04.

A webmail client like Mailpile is a great way to ensure you can access your email from anywhere without the hassle of configuring a standard email client. Mailpile is just a mail client, meaning it only manages existing mail accounts.

By the end of this tutorial, you will have a fully-functional Droplet running Mailpile with Nginx as a reverse proxy.

Please keep in mind throughout this tutorial that Mailpile is still in beta, which means you may encounter bugs and other difficulties along the way. It does not save your information in between sessions. (That is, you’ll have to re-enter your account details every time you restart the Mailpile service.)

It also lacks an easy way to run as a service. By default, it only runs as an interactive script in your SSH session. We’ve included an Upstart script that uses Screen to run it in the background, so you can leave the webmail client up as long as you’d like. This is not recommended for production, however.

Prerequisites

Before we get started, we’ll need a few things:

• A Droplet running Ubuntu 14.04. We recommend at least 512 MB of RAM for a Mailpile setup handling just a few mailboxes. If you expect more than a couple of users, you may want to increase the size
• A user with root access. See this tutorial for instructions on setting up a user with sudo access on Ubuntu 14.04
• An SSL certificate to keep your mail safe. You can purchase one from Namecheap or another certificate authority. If you don’t want to spend any money, you can also make your own for use with Nginx or get one from StartSSL
• A domain name
• If you have a domain ready, create an A record to point to your Droplet (ex. mailpile.example.com). For instructions on setting DNS records with DigitalOcean, see this tutorial on DNS

Make a note of your SSL certificate and key locations. If you followed the tutorial to make certificates for use with Nginx, they will be located at:

• /etc/nginx/ssl/nginx.crt
• /etc/nginx/ssl/nginx.key

That’s it! If you have everything all ready to go, proceed to the first step.

Step 1 — Downloading Mailpile

In this section we will prepare our working environment for the Mailpile installation.

First we need to log into our Droplet. If you haven’t used SSH before, see this tutorial on SSH. Make sure you’re logging into a user with sudo access.

First we need to install Git. We will use Git to clone the Mailpile source from GitHub.

Update Ubuntu’s package lists:

sudo apt-get update

Install Git:

sudo apt-get install git

Now that Git is installed, let’s change our directory to somewhere we can work out of. In this case, we’ll use the /var directory:

cd /var

Clone Mailpile:

sudo git clone https://github.com/mailpile/Mailpile.git

We need the sudo command to allow Git to create a directory inside of /var, which is a system directory.

We’re almost ready to get Mailpile running. Proceed to Step 2 to begin tackling some more requirements.

Step 2 — Configuring Mailpile’s Requirements

In this section we’ll get Mailpile’s requirements installed and configured.

First, let’s install pip. pip is a Python package manager with a few tricks up its sleeve:

sudo apt-get -y install python-pip

pip will allow us to install Mailpile’s requirements more easily. You’ll see how in a minute, but first we need to install a few more things.

Next we need to install lxml. lxml is a Mailpile requirement that would normally be instaled by pip, but we’ve found it to cause the installation to fail for unknown reasons. Because of this, we’ll install it with apt-get:

sudo apt-get install python-lxml

Just a few more packages have to be installed manually, including GnuPG and OpenSSL. These will create a more secure environment for our mail. Some of these will likely be installed by default, but we’ll make sure just in case:

sudo apt-get install gnupg openssl libssl-dev

Now change into Mailpile’s directory:

cd /var/Mailpile

We’re now ready to harness pip’s abilities to install the rest of our requirements.

Mailpile includes a file called requirements.txt, which is basically a list of requirements. pip has the ability to read through this list and automatically install each and every one of them. So let’s do exactly that:

sudo pip install -r /var/Mailpile/requirements.txt

You’re done. All requirements have been installed and Mailpile is ready to use. But before we do, we need to take a few extra steps to tighten our security.

Step 3 — Configuring a Reverse Proxy with Nginx

In this section we’ll configure Nginx as a reverse proxy for Mailpile. This will make Mailpile more secure, allow us to use an SSL certificate, and make it easier to access the webmail client.

With Nginx, instead of accessing Mailpile by visiting https://example.com:33411, you can use https://mailpile.example.com. Let’s get started!

First, we’ll need to have Nginx installed since that’s what’s going to be doing most of the work. So let’s get Nginx before anything else:

sudo apt-get install nginx

Now that Nginx is installed, we can set up the reverse proxy. Let’s edit Nginx’s configuration to tell it to route our subdomain to Mailpile.

We want to delete the original Nginx config file since it’s filled with a bunch of stuff we don’t need. But first, let’s make a backup. First make the directory:

sudo mkdir /home/backup

Now make the backup:

sudo cp -b /etc/nginx/sites-enabled/default /home/backup

Now we are free to delete the file without consequences:

sudo rm /etc/nginx/sites-available/default

Let’s make sure it’s actually gone:

ls /etc/nginx/sites-available/

If you’ve just installed Nginx, the command should return nothing.

Now create a new file:

sudo nano /etc/nginx/sites-available/default

Now it’s time to configure the reverse proxy. Let’s start with the first part. Add the following to the beginning of the file (we’ll explain what it does in a second):

server {
    listen 80;
    return 301 https://$host$request_uri;
}

This tells Nginx to redirect the requests it gets to HTTPS. But in reality, it will try to redirect to something that doesn’t exist yet. Let’s create somewhere for it to go:

server {

    listen 443;
    server_name mailpile.example.com;

    ssl_certificate           /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key       /etc/nginx/ssl/nginx.key;

    ssl on;
    ssl_session_cache  builtin:1000  shared:SSL:10m;
    ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
    ssl_prefer_server_ciphers on;
    
    access_log            /var/log/nginx/mailpile.access.log;

Note: make sure your certificate and key are located at /etc/nginx/ssl/nginx.crt and /etc/nginx/ssl/nginx.key. Otherwise, update the paths next to ssl_certificate and ssl_certificate_key to match your certificate and key locations.

What we just entered told Nginx to listen on port 443 (the port websites with SSL access, as opposed to port 80), apply our SSL certificate, and turn SSL on. Now we need to actually serve something to this new HTTPS URL we’ve redirected to and enabled SSL on. We’ll do that next.

Add the following below the previous two blocks:

    location / {

      proxy_set_header        Host $host;
      proxy_set_header        X-Real-IP $remote_addr;
      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header        X-Forwarded-Proto $scheme;

      # Fix the "It appears that your reverse proxy set up is broken" error.
      proxy_pass          http://localhost:33411;
      proxy_read_timeout  90;

      proxy_redirect      http://localhost:33411 https://webmail.example.com;
    }
   }

When you’re all done, the completed config file should look something like this:

server {
    listen 80;
    return 301 https://$host$request_uri;
}

server {

    listen 443;
    server_name mailpile.example.com;

    ssl_certificate           /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key       /etc/nginx/ssl/nginx.key;

    ssl on;
    ssl_session_cache  builtin:1000  shared:SSL:10m;
    ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
    ssl_prefer_server_ciphers on;

    access_log            /var/log/nginx/mailpile.access.log;

    location / {

      proxy_set_header        Host $host;
      proxy_set_header        X-Real-IP $remote_addr;
      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header        X-Forwarded-Proto $scheme;

      # Fix the "It appears that your reverse proxy set up is broken" error.
      proxy_pass          http://localhost:33411;
      proxy_read_timeout  90;

      proxy_redirect      http://localhost:33411 https://webmail.example.com;
    }
   }

If you did not replace the default site, but instead created a server block file with a different name, you will need to enable it with a command like this:

sudo ln -s /etc/nginx/sites-available/mailpile.example.com /etc/nginx/sites-enabled/

The default site should already be enabled.

Please read this article about Nginx server blocks if you would like to learn more.

Now restart Nginx to reload the configuration:

sudo service nginx restart

That’s it. Now Mailpile is ready to be reached at https://mailpile.example.com. You may have to accept the SSL warning if you used a self-signed certificate.

Also, accessing http://mailpile.example.com will automatically redirect to the SSL version of the site.

We haven’t run Mailpile yet, so if you visit those URLs now, you’ll see a 502 Bad Gateway error. The most common reason for this error is that the Mailpile application is not running.

Proceed to Step 4 to run Mailpile.

Step 4 — Configuring and Running Mailpile

In this section we’ll start Mailpile, and configure it to work with our reverse proxy.

Make sure we’re in the correct directory:

cd /var/Mailpile

To run Mailpile, enter:

./mp

You can start exploring Mailpile through the command line or the web interface now.

Mailpile should now be live at https://mailpile.example.com, and even redirect to HTTPS using your SSL certificate. Congratulations!

You can use CTRL-C and then type quit to quit Mailpile.

Optional — Make Mailpile a Service with Upstart

To ensure Mailpile is always active and ready to handle your mail, you can convert Mailpile to a service, using Upstart. Follow this wonderful tutorial for instructions.

Since Mailpile is in beta, it hasn’t been properly daemonized yet. It also requires an interactive command line, so you can’t just directly run the Python script. This Upstart script is a hacky way of running the Python app as a service through Screen:

sudo nano /etc/init/mailpile.conf

description "Mailpile Webmail Client"
author      "Sharon Campbell"

start on filesystem or runlevel [2345]
stop on shutdown

script

    echo $$ > /var/run/mailpile.pid
    exec /usr/bin/screen -dmS mailpile_init /var/Mailpile/mp

end script

pre-start script
    echo "[`date`] Mailpile Starting" >> /var/log/mailpile.log
end script

pre-stop script
    rm /var/run/mailpile.pid
    echo "[`date`] Mailpile Stopping" >> /var/log/mailpile.log
end script

This script will start Mailpile and keep it up as long as the Screen session is running. It does not properly stop the Screen session, so you’ll have to stop the Screen session manually if you want to stop Mailpile.

With this script, you can start Mailpile with:

sudo start mailpile

This will result in a Screen session called 12345.mailpile_init owned by the root user.

However, the other Upstart commands will not work. You will have to end the Screen session manually. Also, if the service crashes or is stopped, you’ll have to start it again and reset all your preferences.

Step 4 — Getting Started with Mailpile

This section covers basic Mailpile use from the webmail interface, at https://mailpile.example.com.

Here is the screen you’ll see when you visit Mailpile for the first time.

Choose a language from the dropdown menu.

Click the Begin button.

Create a new password, then enter it twice.

Click the Start using Mailpile button.

The Login Screen: please enter the password you just created.

Add a new account with the + Add Account button.

From here, you’ll need to enter details for a mail account you own. You should enter the email address and password for that specific mail account. Mailpile will then attempt to connect to your account with those credentials, which can take a few minutes.

You can also enter the Sending Mail and Receiving Mail credentials manually, if Mailpile can’t figure them out itself.

Once you log in, you’ll be presented with this screen:

Try sending and receiving a test email for the account you added to Mailpile to a different email account. If this is successful, you’ll know Mailpile is working with your email address.

Other Mailpile features

Mailpile also offers a wide variety of encryption options:

Conclusion

To get started with Mailpile, see the FAQ.

For more configuration options, run help from the Mailpile command line.

Congratulations, you now have your very own webmail client, Mailpile, running on a Ubuntu 14.04 Droplet. It is fully equipped with SSL and automatically redirects to the HTTPS version of your site. You may now set up your email accounts and manage your contacts, mail, categories, and more with Mailpile’s beautiful interface. Have fun!