Welcome Slashdot readers: the advanced module is free to you for a limited time.

Installation Guide

You can install Filtered on any PHP & MySQL capable server. Since you may want to experiment with Filtered without committing your own server resources, I’ve written this installation guide for Ubuntu 12.x on Digital Ocean, an inexpensive cloud hosting service.

Digital Ocean makes it easy for you to startup an instance of Filtered and shut it down again if you don’t want to keep it. They also have a bunch of handy tutorials for configuring their droplets.

Note: If you’d like to setup Filtered using our mostly pre-configured Digital Ocean Droplet, Request a Droplet.

If you’d like to set up Filtered on Amazon’s Cloud Services (AWS), check out my installation guide for WordPress on AWS. The steps for setting up Filtered are very similar if you browse the sign up for AWS, create an instance and secure your instance sections.

If you’re interested in having a custom installation of Filtered, paid options for AWS, Digital Ocean, Linode et al. are available.

Note: While you can run Filtered from your own desktop machine, you’ll most likely need to manually compile IMAP-SSL support in PHP to access your gmail and other e-mail accounts. Here’s more information on the topic of IMAP-SSL.

Getting Started

Sign up for a Digital Ocean account and create a droplet. Droplet is the term Digital Ocean uses for server instances. You can start with the 512 MB instance which costs $5 per month. Filtered runs tightly in this configuration. You may ultimately need a swap file or a 1GB instance ($10/mo.) if you run into memory problems.

Create a Droplet

You will need to provide a hostname to access your server. You can set up your own domain name e.g. MailFilter.com or a subdomain of your personal domain e.g. filter.yourname.com.

Under Select Image, click the Applications tab, then “Lamp on Ubuntu 12.04”. Or, if you want to manually configure your droplet, choose Ubuntu 12.04.3 x64.

Configure the DNS Record for Your Domain Name

Digital Ocean will email you your new server configuration. Once you have your IP address, visit your Domain Name registrar and set up an A record pointing from your hostname e.g. filter.yourdomain.com A record pointing to your digital ocean IP address e.g. filter.yourdomain.com A => 161.242.200.199.

You may wish to read the Mailgun section below as well at this point so you can configure TXT and MX DNS records for Mailgun at this time.

It may take a few hours or more for your DNS records to propagate before you can access your server and the Filtered web interface using your hostname. However, you should be able to continue the setup process using the Digital Ocean IP address.

Setting Up Your Server

Digital Ocean will have provided you with a username (root) and password. Using Terminal on Mac OS X or an SSH application on Windows like Putty, you can log into your server.

ssh root@your-ip-address e.g. ssh root@161.242.200.199

or

ssh root@filtered.yourdomain.com

If you plan to keep your droplet, you will want to take steps to better secure it. I provide examples for using key-based logins here (Secure Your Instance) and turning off root login – which is more vulnerable to hacking. Digital Ocean also has a helpful tutorial.

Note: Security is important because someone could theoretically access your email account password if they gain access to your service.

Filtered requires a PHP & MySQL stack on your server. If you’ve used the Digital Ocean LAMP stack application to start, you have most of the packages you’ll need.

However, you’ll need to install the Imap library for PHP:

apt-get install php5-imap

If you’re going to manually configure your server, you’ll likely need to install most of these packages or their equivalents:

apt-get install php5 php5-mysql php5-curl php5-imap php5-mcrypt
libapache2-mod-php5filter libapache2-mod-php5 libapache2-mod-auth-mysql

Digital Ocean has this helpful Ubuntu LAMP tutorial if you need more information.

Configure MySQL Access

Definitely change your MySQL administrator from password to something new:

sudo mysqladmin -u root -p password

Now, sign into MySQL with your new password:

mysql -u root -p

Create a database for Filtered to use:

create database db_filtered;

Create a username and password for the database. You can replace the database, name, and password with your own choices:

create user user_filtered_11@localhost;

Set the password for your new user and grant and flush privileges:

set password for user_filtered_11@localhost= PASSWORD("x53xcdeg343");
grant all privileges on db_filtered.* TO user_filtered_11@localhost
IDENTIFIED BY 'x53xcdeg343';
flush privileges;
exit;

Download the Filtered Code

You can download a package of the code from the mail_filter Github repository but it may be easier if you use git to clone the Filtered tree.

wget --no-check-certificate https://github.com/newscloud/mail_filter/tarball/initial-beta-v0.75 -O - | tar xz

Move the resulting files to /var/www/mail_filter:

sudo mv newscloud-mail_filter-fxxxxx /var/www/mail_filter

Provide permissions for Apache to access the code directories:

cd /var/www
sudo chown www-data:www-data * -R 
sudo usermod -a -G www-data root

Configure the Apache Site Definition for Filtered

Now, it’s time to create a site configuration file for your Apache server to host Filtered:

cd /etc/apache2/sites-available

Let’s create a new file to edit:

sudo nano mail_filter

Paste in the sample site file below and be sure to replace the naming convention for your domain name:

<VirtualHost *:80>
   ServerName FILTERED.YOURDOMAIN.COM
   DocumentRoot /var/www/mail_filter/app
   DirectoryIndex index.php
   <Directory /var/www/mail_filter/app/>
      AllowOverride All
      Order Deny,Allow
      Allow from all
   </Directory>
</VirtualHost>

Turn on mod rewrite and turn off the default Apache site:

sudo a2enmod rewrite
sudo a2dissite 000-default

Tell Apache to enable the site and reload:

sudo a2ensite mail_filter
sudo service apache2 restart

Configure the Filtered Authentication File

Create a directory for storing your Filtered authentication codes.

mkdir /var/secure
cd /var/secure

Copy the sample configuration file here:

cp /var/www/mail_filter/docs/sample-config.ini /var/secure/filtered.ini

Edit the file and fill in all settings with your own accounts and passwords:

sudo nano filtered.ini

The Mailgun and Pushover codes can wait until after you’ve set them up.

Run the Database Migrations

The Yii Framework uses Active Record migrations to programmatically build your database:

cd /var/www/mail_filter
./app/protected/yiic migrate up

When prompted, enter your administrator username, email and password. This is what you’ll use to log in to the Filtered website.

Admin login [admin]: do_filtered
Admin email [webmaster@example.com]: you@yourdomain.com

You should be ready to go. Try visiting your web page:

http://filtered.yourdomain.com

Login with your user name and password.

If you run into any issues, double check the above instructions or post a question to our support forum. You can check the Yii application log this way:

tail -n 100 /var/www/mail_filter/app/protected/runtime/application.log

Report issues or bugs to the Github issues page.

Paid installation or technical support is also available.

When you’re ready to continue, follow the instructions for configuring Mailgun and your background tasks below and then read Getting Started with Filtered.

Sign Up for a Mailgun Account

Filtered uses Mailgun.com’s email service for sending email digests and white list challenge messages. This eliminates the need of running a Postfix mail server and its associated complexities. It also reduces the chance that outbound mail will be filed as spam. Mailgun offers up to 10,000 outbound emails monthly for free – so it’s unlikely to cost you anything. Sign up for Mailgun here.

Add your hostname as a domain in the Mailgun control panel. You will need to create two more DNS TXT records to enable Mailgun to send from your domain. Follow the instructions here.

If you wish to set up your domain to receive catch-all email addresses for anonymity’s sake, you’ll also need to set up DNS MX records as Mailgun describes. Then you’ll be able to receive messages at any_mailbox@yourdomain.com and have them forwarded and processed by Filtered. You can set up a Mailgun route to forward all messages from your Filtered domain to your email account.

If you wish to use Postfix to send mail from your server, you’ll need to search the Filtered code for the Yiigun component and replace email sending calls with your preferred PHP-based mail solution. These two pages may be helpful: PHP Mail and Sending HTML Email with PHP.

Configure the Background Tasks

You’ll need to activate cron and tell it to run the background tasks that Filtered requires. You can customize the /docs/crontab.txt file with your domain name and paste that into the crontab file editor.

sudo crontab -e

When you save the crontab file, sudo crontab -l will show you the results. It should contain the following lines:

# m h dom mon dow command
*/1 * * * * wget -O /dev/null http://yourdomain.com/daemon/inbox
*/5 * * * * wget -O /dev/null http://yourdomain.com/daemon/index
15 23 * * * wget -O /dev/null http://yourdomain.com/daemon/daily
35 * * * * wget -O /dev/null http://yourdomain.com/daemon/hourly
15 0 * * 0 wget -O /dev/null http://yourdomain.com/daemon/weekly

You can learn more about what these tasks are doing in How Filtering Works.

You may want to check your maximum PHP session lifetime, gc-maxlifetime. On my server, most cron tasks complete with a few seconds. However, some of the advanced features may take longer. If you change gc-maxlifetime in your php.ini file, you will need to restart Apache.

[button link=”/filtered-open-source-imap-mail-filtering-software-for-php/getting-started/” size=”medium” variation=”red” textColor=”#ffffff” align=”right”]Continue…[/button]