Setting up manitou-mdx

1) Perl modules

manitou-mdx depends on Perl 5.8, with those CPAN modules:

Perl modules may be available as packages for your system. For example, on a debian system, they're provided by the following debian packages:

2) Build

3) Configuration file

The 0.9.4 and upper versions use a configuration file, installed in /etc/manitou-mdx.conf by default.

4) Running

If possible, manitou-mdx should be run under its own unix account, such as manitou, since it makes it easier to deal with various permissions and security issues. Otherwise, it can run under any non-system account. Running under the root account should be avoided.

The most convenient way is to let the script run all the time. It can be launched by: 

$ nohup manitou-mdx --conf=/path/to/config_file </dev/null >>/var/tmp/manitou/mdx.log 2>&1 &

manitou-mdx can run either on a different machine than the database server, or on the same machine. From the database server's point of view, it is just a client application and can run anywhere as long as it is permitted to connect.

For a non-root install, it might be necessary to set the PERL5LIB environment variable to point to the directory into which the mdx Perl modules have been installed, for example $HOME/install_path/lib/perl5/site_perl/5.8.6

5) Importing an existing mailbox in mbox format

perl manitou-mdx --conf=/path/to/config_file --mboxfile=/path/to/mboxfile \
  [--tag=optional_tagname] [--status=1] [--mailbox=dest@domain.tld]
If you haven't made a config file yet, the --conf option can be left out if there is a MANITOU_CONNECT_STRING environment variable containing valid DBI connection parameters to connect to the database.
If the --tag option is used and the tag doesn't exist, it will be created.
Use the --status=1 option to mark the imported mail as already read, otherwise all messages will considered as new.
Optionally use the --mailbox argument to specify to what mailbox the messages should be assigned. The mailbox will be created in the database if it doesn't exit.
Finally, after importing large volumes of mail, it is advised to run a PostgreSQL ANALYZE command so that the database statistics are updated.

6) Delivering incoming mail into files for manitou-mdx

It is assumed that the incoming mail that has to be processed by manitou is forwarded to a local unix account (such as fetchmail does). One of these two methods may be used:

System-wide installation

The script/store_mail.sh file from the source archive should have got installed into a location such as /usr/local/bin. Edit it to change the MANITOU_MAILFILES_DIR variable to where your mail files are to be spooled. The value of the variable should match a mailfiles_directory entry from the configuration file. For several mailboxes, several copies of store_mail.sh can be installed, each one with its own MANITOU_MAILFILES_DIR.

Edit the /etc/aliases file to make your incoming mail being piped into store_mail.sh: 

myaccount: "|/usr/local/bin/store_mail.sh"
Run `newaliases` for the aliases file to be reloaded.

User-private installation (using procmail)

Copy the script/store_mail.sh file from the source archive into a location such as $HOME/bin. Edit it to change the MANITOU_MAILFILES_DIR variable to where your mail files are to be spooled (inside your home directory if you want to keep your installation private)

Add the following lines at the end of the private .procmailrc file: 

:0
|$HOME/bin/store_mail.sh
It is also possible to use a simple .forward file instead of procmail; refer to your mail delivery agent documentation on how to set up a .forward file.

7) Monitoring

Once the previous step is done, each new incoming mail should come up as a new file in a mailfile directory. It is created with a .received suffix, which gets renamed to .processed as soon as manitou-mdx has imported it into the database. manitou-mdx will check periodically for new files in these directories.

It is also possible to monitor via the runtime_info table of the database. See the alive_interval entry in the configuration file's documentation for more information.