Welcome to Mini VMail
Mini VMail is a RoR web application to manage virtual users and domains for a mail server. This is a minimalistic implementation that offers just editing of domains, mailboxes and forwards. Mini VMail is developed and used with PostgreSQL, but should work with any database that's supported by ActiveRecord.
For now, it is very advisable to be familiar with Ruby on Rails application structure and configuration.
Sample configuration files are provided for Dovecot (v2.0) and Postfix, but the database schema may be usable by other mail systems as well, as long as mailbox path and delivery user id is configurable in the MDA configuration.
Note that this project is developed with limited time, for one specific in-house usage scenario. Flexibility and usability for other usage may be limited. Still feel free to send me improvement suggestions or even pull requests with improvements.
- Adapt config/deploy.rb and deploy Mini VMail with capistrano
- Open the deployment URL with a browser
- Follow the instructions to set up the initial administrator account
- Setup an additional user account to edit just mailbox and forward data
- Add at least one domain for which you want to receive mails
- Download the mail server configuration files to your mail server. Database connection details are already filled in. Adapt to your needs if necessary
- Add mailbox and forward (alias) entries
Configuring virtual mail domains in Postfix
In all described scenarios: never add domains configured in Mini VMail to
virtual_mailbox_domains vs. relay_domains
Postfix offers the
virtual_mailbox_domains address class to deliver mails locally to virtual users. Delivery happens by default with the
included "virtual" delivery agent. This does not work well with Mini VMail as the database does not contain a mailbox path. Therefore an external delivery mechanism such as
dovecot-lda or LMTP is needed.
While it is possible to configure such a delivery agent for virtual mailbox domains, such a setup is conceptually closer to relaying to an external system. Thus it is best to configure the domains for Mini VMail as
As the domains table contains a transport field, the same table can be used as
transport_maps as well as
relay_domains map. The default transport for new domains is configured in
local domains map file vs. SQL lookup configuration
For many mail server setups, the list of hosted domains does not change very often. As local map files are always faster and more robust, you might want to export the domain map and use that in postfix. Use the link at the mail server configuration downloads for that.
- for most cases just use the SQL configuration
- if your domain list changes very infrequently and you're concerned about limiting the number of SQL queries export the domain list
Configuring the list of valid recipients for postfix
Recent postfix versions provide recipient address verification which can be used to determine valid addresses for the hosted domains. This only works for SMTP and LMTP destinations. If this is not used, the list of valid recipient must be explicitly configured in postfix, as
virtual_mailbox_mapsif the domains are configured as
relay_recipient_mapsif the domains are configured as
Use recipient verification if:
- mail is delivered with LMTP or SMTP and
- verification cache is properly configured and monitored
Be sure to apply recipient verification only to the destination domains under your own control.
In all other cases use an explicit recipient map.
Configuring mail aliases in postfix
The forwards table can be used for virtual aliases in postfix. Virtual alias mappings are applied to all mail, but postfix must be configured to accept mails for domains that are used only for aliases. Postfix offers the virtual alias domain address class with the
virtual_alias_domains list for that, but Mini VMail does not support that.
A relay or virtual mailbox domain with no mailbox recipients, but only alias addresses is almost identical to a specialized virtual alias domain, so just add domains intended for forwards only in Mini VMail, and configure the SQL lookup for
Configuring Mini VMail
The first user created during setup is an administrator account that can download mail server config, edit domains and add more users through the web interface. All further users are unprivileged users who can only edit mailboxes and forwards. Currently there is no way to configure more administrator users. If needed, this can be achieved by setting admin=true for an existing User object in a database or Rails console.
The default transport is configured in
config/config.yml, and is used as initial value for new domains. The other settings in
config.yml may not be changed for now, as that would require code changes right now.
Note that in the repository,
database.yml are not directly supplied, but the versions in config/deploy/ are copied to the server by capistrano. To run locally, copy these files to the config/ directory.
Server Setup with Debian 7
- Apache Web Server
- apache2-mpm-worker, apache-threaded-dev
- Build requisites for Ruby, Passenger and Rails
- autoconf bison build-essential libssl-dev libyaml-dev libreadline6 libreadline6-dev zlib1g zlib1g-dev git-core libcurl4-openssl-dev nodejs
- postgresql libpq-dev
Setup on Server
- create user for deploying and running, with shell and SSH login with key auth
- configure passwordless sudo access for that user
- perform following steps as that user:
- install rbenv and rubybuild (as rbenv-plugin)
- install ruby (2.0+) with rbenv (exact version should be updated)
rbenv install 2.0.0-p353
- set ruby version
rbenv global 2.0.0-p353
- install bundler and passenger gems
gem install bundler passenger ; rbenv rehash
- install passenger apache module
- save passenger apache config as
a2enmod passenger && service apache2 restart
- create app base directory and make depoy user the owner
- create database user
- following deployment steps are done with capistrano from a client machine
- needs to have key-based ssh access to deploy user on target
- needs ruby with bundler locally
- checkout mini_vmail repository (in branch to deploy) and cd into
- installs capistrano and app libraries locally
- configure servername, usernames and domain name for target server
- configure branch or tag (either in variable
bundle exec cap deploy:setup
- this sets up all directories and config files
- prompts for database host and password
bundle exec deploy:first
- deploys application version
- creates and initializes database
- creates apache vhost configuration and enables it
- further updates are performed by
bundle exec deploy