Show INSTALL syntax highlighted
Read QUIRKS first!
REQUIREMENTS
============
- Apache 2 with mod_perl 2.x and HTML::Mason.
- C++ Boost libraries 1.33 or better.
- A decent C++ compiler. See imap_webcache notes for information on compiler
problems.
- A number of perl modules (configure will tell you what you need, and if you
have it)
- A number of utilities if you want viewers to work (antiword, netpbm, xlhtml,
unzip, tar)
- The elinks text browser (which is used to convert HTML messages to text). I
hope to drop this dependency soon.
- An RFC-3501 compliant IMAP server. I have verified compatibility with
- Dovecot 1.0beta
- UW-IMAP
- Cyrus 2.3.1 (Note, versions prior to 2.2.8 will definitely _not_ work, due
to bounds checking bug in Cyrus)
DOCS - NEW!
===========
There is now an admin guide in the docs subdirectory (in POD format). Use
pod2man to turn it into a man page, or pod2html to turn it into HTML (which
includes pictures).
The notes below should be up to date a a quick guide. Look for more specific
details in the admin guide.
Add requests for the creation of specific docs to the bugzilla database
(http://whizzo.uoregon.edu/bugzilla).
UPGRADING
=========
If upgrading, it is a good idea to clean out your mason cache (mason
subdirectory of your install)
Also re-run alphamail_genconfig! Don't expect the configuration files to
remain static. Dependencies and configuration parameters may change.
IMPORTANT NOTE: Upgrading from pre-0.70 to 0.70 or above: The prefs file naming
changed. The old names used the imap servers as part of the file names. This
was a problem, since more than one MX can use the same imap server. If you have
existing users, rename the config files using the script util/upgrade_prefs.
BUILD NOTES (platform specific notes may be available in notes/)
===========
1) Building and installing.
If you are NOT using g++, then you should look at your compiler manual and
add some optimization (and possibly debugging) options to CXXFLAGS (see also
the files in notes/). Speedups of more than 50% are common when optimization
is enabled, but the configure system only knows how to do this for GNU
tools.
Many systems also need an extra option to enable thread support in the
compiler (-pthread on Linux, -pthreads on Solaris).
You may also need to specify where the Boost headers and libraries are
located. Here is an example:
$ export CXXFLAGS=-I/usr/local/include/boost-1_33_1 -O2 -g -pthread
$ export LDFLAGS=-L/usr/local/lib
$ ./configure --prefix=/usr/local/alphamail
$ make
$ su -
# make install
The configure script will try to auto-detect the boost library names on
your system they are either in system library locations, or you specify an
LDFLAGS -L option that indicates their location.
If you have a Boost toolset that was not documented as of early 2006, or if
you have more than one toolset and want to force configure to use a specific
one then you may have to tell the configure script which toolset to use.
If you have this problem, look at your library names
(libboost_regex-gcc-mt.a) for the abbreviation between the library name and
mt (in the example case, it is gcc) and use:
$ ./configure --prefix=/usr/local/alphamail --enable-boost-toolset=abb
where abb is the abbreviation in your library names.
If there are errors on dependencies, fix them before moving on to
configuration. You can use CPAN or your system's package manager. I have
made a special effort to insure that most of the dependencies are widely
available as prebuilt packages.
2) As root, generate a configuration file using the interactive generator:
# alphamail_genconfig
This will complain if some of the viewer utilities are not available. The
only one that should affect operability is elinks.
3) Install the garbage sweeper (from util) in your crontab (see notes below)
Other notes on dependencies:
netpbm-progs is needed for image icon previews
antiword is needed for word doc previews
xlhtml is needed for excel previews
elinks is needed for html message to text conversions (soon to go away)
CONFIGURATION
=============
The alphamail_genconfig script generates an Apache and web app configuration
file, creates util directories, and fixes privileges on certain files.
YOU MUST RUN THIS AS A PRIVILEGED USER.
You should be able to simply include the apache/alphamail.conf file it creates
in your Apache 2 configuration. SSL is required, unless you hand edit the
resulting configuration.
Please report confirmed bugs to:
http://whizzo.uoregon.edu/bugzilla
If you are having general issues with building or installing on a certain
platform you should use the mailing lists.
SANDBOX PROBLEMS?
=================
All external viewers run in a sandbox (see utils/sandbox/sandbox.c), which you
configure when you run the configuration script. The script tries to make sure
all dependencies are met, but you may find you need to link more files into the
sandbox in order to get things to work. Use ln(1) for this purpose if possible,
or cp if you have separate filesystems.
It currently makes some assumptions about the OS (i.e. Linux or OSX), but I am
trying to add support for others. Basically, the configure script tries to copy
all binaries and libraries into the sandbox that will be needed for a chroot
jail. You can look at what the script tries, and if it fails, just emulate it
via the command line (i.e. make your own chroot area that can run netpbm,
antiword, etc) and comment out the create_sandbox code in alphamail_genconfig.
GARBAGE SWEEPER
===============
Files build up in the temporary directories as the system is used. There is
no way to guarantee their cleanup from within the web-app, because the user may
not log out, etc. So, there is an external utility called garbage_sweeper in
the util directory. Install it in your crontab. You might run it first and look
at the alphamail_ui.log to make sure it is doing the correct thing.
My crontab entry looks like this:
0,10,20,30,40,50 * * * * /usr/local/alphamail/util/garbage_sweeper --config /usr/local/alphamail/etc/alphamail_config --lib /usr/local/alphamail/lib
MEMORY USAGE
============
Perl may "leak" due to the fact that garbage collection is in use and circular
references may be created. I have done my best to insure that my code doesn't
do this, but I am using a lot of other people's modules. The best way to keep
things in shape is to set MaxClientRequests in httpd.conf to something other
than 0. I use about 200. There is very little penalty in this, and it keeps
apache's memory footprint in check.
See more files for this project here