Transactional email server with a lovely web interface
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
app Now admin uses api to toggle dkim Oct 10, 2018
bin Run rake rails:update and add files/changes that look OK Nov 7, 2016
config Style fixes Oct 4, 2018
db Style fixes Oct 3, 2018
dockerfiles pids don't get cleared out properly. So, clear before starting Aug 20, 2018
lib Get current value using the API Oct 10, 2018
log rails new . --skip-test-unit Mar 30, 2013
postfix_log/supervisor Log postfix to local file Aug 19, 2018
provisioning Rename rvm_io.ruby to rvm.ruby Oct 8, 2018
public rails new . --skip-test-unit Mar 30, 2013
spec Now admin uses api to toggle dkim Oct 10, 2018
vendor/assets Add bootstrap extension for making row on table clickable Apr 1, 2013
.dockerignore Speed up docker builds by not including everything Aug 18, 2018
.env Now have a container to suck up the log entries Aug 20, 2018
.gitignore Log postfix to local file Aug 19, 2018
.rspec When running rspec on its own use spec_helper Aug 6, 2018
.rubocop.yml Style fixes Oct 4, 2018
.ruby-version Update ruby version to 2.5.1 Sep 2, 2018
.travis.yml Merge branch 'after-upgrade-ruby-and-gems' into graphql-api Aug 21, 2018
Capfile Style fixes Oct 4, 2018
DESIGN-PRINCIPLES.MD Add a first pass of some "design principles" Aug 13, 2018
Gemfile Style fixes Oct 4, 2018
Gemfile.lock Add rubocop gem for development Oct 2, 2018
Guardfile Style fixes Oct 4, 2018
LICENSE.txt Change license to AGPL Jun 6, 2013
Procfile Don't need the seperate api process in development anymore Aug 2, 2018
Procfile.production Remove delayed_job gem Jan 12, 2015
README.md Update README with information about how long it's been used Sep 22, 2018
Rakefile Style fixes Oct 4, 2018
Vagrantfile vm needs more memory Dec 16, 2014
ansible.cfg Set standard ansible config in ansible.cfg Jun 26, 2018
config.ru Style fixes Oct 4, 2018
cuttlefish.sublime-project change signature method Apr 10, 2013
docker-compose.yml Improve mount performance on os x Sep 21, 2018
provision_production.sh Set standard ansible config in ansible.cfg Jun 26, 2018

README.md

Stories in Ready

Cuttlefish Cuttlefish

Build Status Coverage Status Maintainability

Cuttlefish is a lovely, easy to set up transactional email server

Sending a few emails from your app is easy. Sending lots becomes painful. There are so many hidden gotchas. Do your emails get delivered? Are you being considered a spammer? What about all those bounced emails?

Let's make sending lots of emails fun again!

And without the hidden dangers of vendor lock in of commercial transactional email services.

  • Send email from your application using smtp in the usual way and get all sorts of added benefits for no effort
  • A lovely web UI to browse what's happening
  • Monitor in real time which emails arrive at their destination and which bounce
  • Works with any web framework and language
  • Automatically not send emails to destinations that have hard bounced in the past
  • Track which emails are opened and which links are clicked
  • Statistics on emails sent, soft/hard bounced and held back
  • View the full email content for recently sent emails
  • Multiple applications can each have their own SMTP authentication
  • Check your IP reputation with one click
  • Easy to install and get going quickly
  • Built in, super easy to set up, automatic DKIM signing
  • Postfix, which you know and trust, handles email delivery
  • Open source, so no vendor lock in.

Cuttlefish is in beta. It's been used in production by OpenAustralia Foundation's projects for several years and has sent many millions of emails.

Screenshots

Sign up Dashboard Email

Things on the cards

  • REST API for deep integration with your application
  • Web callbacks on successful delivery, hard bounces, open and click events
  • "out of office" and bounce reply filtering
  • Incoming email

Dependencies

Ruby 2.5.1, PostgresQL, Redis (2.4 or greater), Postfix (Postfix is optional for local development or just trying it out. Some things like the email deliverability just won't show anything)

Also you need the following libraries: imagemagick, libmagickwand-dev, libmysqld-dev

Development

Setting up a local development environment with all the correct dependencies and moving parts is now very straightforward by using Docker.

To start with:

docker-compose build
docker-compose run web bundle exec rake db:setup

Then

docker-compose up

Those steps will take a little while as they download images and build the docker containers.

When its stops spitting output to the console point your web browser at

http://localhost:3000

For development all mail sent out by Cuttlefish will actually go to mailcatcher. To see the mailcatcher mail:

http://localhost:1080

To run the tests (do that from another window):

docker-compose exec web rake

To install:

We use Vagrant and Ansible to automatically set up a fresh server with everything you need to run Cuttlefish. It's a fairly complicated affair as Cuttlefish does have quite a few moving parts but all of this is with the purpose of making it easier for the developer sending mail.

These instructions are specifically for installing the server at https://cuttlefish.oaf.org.au.

To install to a local test virtual machine

  1. Create a file ~/.cuttlefish_ansible_vault_pass.txt which contains the password for encrypting the secret values used in the deploy. The encrypted variables are at provisioning/roles/cuttlefish-app/vars/main.yml.

  2. Download base box and build virtual machine with everything needed for Cuttlefish. This will take a while (at least 30 mins or so)

vagrant up
  1. Deploy the application. As this is the first deploy it will take quite a while (5 mins or so). Further deploys will be much quicker. We're using the --set-before local_deploy=true flag to deploy to your local test virtual machine instead of production.
bundle exec cap --set-before local_deploy=true deploy:setup deploy:cold foreman:export foreman:start
  1. Add to your local /etc/hosts file
127.0.0.1       cuttlefish.oaf.org.au
  1. Point your web browser at https://cuttlefish.oaf.org.au:8443/

To install on Linode

  1. Login at the Linode Manager

  2. Add a new Linode

  3. Select "Linode 2048" at location "Fremont, CA"

  4. Select your new Linode in the dashboard

  5. Click "Deploy a Linux Distribution". Choose "Ubuntu 14.04 LTS" and choose a root password. Leave everything as default.

  6. Click "Boot" and wait for it to start up

  7. Update provisioning/hosts with the name of your server (e.g. li123-45.members.linode.com)

  8. Create a file ~/.cuttlefish_ansible_vault_pass.txt which contains the password for encrypting the secret values used in the deploy. The encrypted variables are at provisioning/roles/cuttlefish-app/vars/main.yml.

  9. To provision the server for the first time you will need to supply the root password you chose in step 5. On subsequent deploys you won't need this. To supply this password edit the ./provision_production.sh script and temporily add the --ask-pass argument to the last command, then run the script:

./provision_production.sh
  1. Update the server name in config/deploy.rb

  2. Deploy the application. As this is the first deploy it will take quite a while (5 mins or so). Further deploys will be much quicker

cap deploy:setup
cap deploy:cold
cap foreman:export
cap foreman:restart
  1. At this stage you might want to snapshot the disk

  2. Make sure that DNS for cuttlefish.oaf.org.au points to the server ip address

  3. Point your browser at https://cuttlefish.org.au

At this point you should have a basic working setup. You should be able to send test mail and see it getting delivered.

Some further things to ensure things work smoothly

  1. Add DNS TXT record for cuttlefish.oaf.org.au with "v=spf1 ip4:your.server.ip4.address ip6:your.server.ip6.address -all"

  2. Set up incoming email for cuttlefish.oaf.org.au (In OpenAustralia Foundation's case using Google Apps for domain). Add addresses contact@cuttlefish.oaf.org.au, bounces@cuttlefish.oaf.org.au and sender@cuttlefish.oaf.org.au

  3. Ensure that the devise email address is set to contact@cuttlefish.oaf.org.au

  4. Set up reverse DNS. In the Linode Manager under "Remote Access" click "Reverse DNS" then for the hostname put in "cuttlefish.oaf.org.au" and follow the instructions. This step is necessary in order to be able to sign up to receive Feedback loop emails.

Deploying to production

One gotcha is that we're still on Capistrano 2 which doesn't apply database migrations by default on deploys.

For normal deploys

cap deploy

To rollback a failed deploy

cap deploy:rollback

To deploy and run the migrations

cap deploy:migrations

Screenshots

Done some development work which updates the look of the main pages? To update the screenshots

bundle exec rspec spec/features/screenshot_feature.rb

Then commit the results

How to contribute

If you find what looks like a bug:

  • Check the GitHub issue tracker to see if anyone else has reported issue.
  • If you don't see anything, create an issue with information on how to reproduce it.

If you want to contribute an enhancement or a fix:

  • Fork the project on GitHub.
  • Make your changes with tests.
  • Commit the changes without making changes to any files that aren't related to your enhancement or fix.
  • Send a pull request.