Show INSTALL syntax highlighted
Read QUIRKS first!
REQUIREMENTS
============
- AlphaMail runs on Apache 2.
- 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)
- C++ Boost libraries 1.33 or better
- A decent c++ compiler. See imap_webcache notes for information on compiler
problems.
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. Speedups
of more than 50% are common when optimization is enabled, but the configure
system only knows how to do this for GNU tools:
You may also need to specify where the Boost headers and libraries are
located:
$ export CXXFLAGS=-I/usr/local/include/boost-1_33_1 -O2 -g
$ 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.
2) As root, generate a configuration file using the interactive generator:
# alphamail_genconfig
If there are errors on dependencies, fix them before moving on. 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.
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 util/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 etc/apache/alphamail.conf file in your
Apache 2 configuration. SSL is required.
Please report problems to:
http://whizzo.uoregon.edu/bugzilla
SANDBOX PROBLEMS?
=================
All external viewers run in a sandbox (see utils/sandbox/sandbox.c), which you
specify when you run the configuration. 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), 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