Installation Instructions
-------------------------

These instructions assume that you know something about web servers,
CGI programs, mail servers and so on.  If you get stuck, do get in
touch (though I can't promise to be able to help).  Contact details
can be found via the web page (http://decimail.org/webmail/).


Obtain the latest tar file from the website.

Untar it in some suitable location on your web server.

Set up your web server configuration so that the .cgi files will be
executed as perl CGI programs, and to restrict access to this
directory using HTTP authentication.  See your web server
documentation for how to do this.  If you're using Apache, here's an
example .htaccess file that might do what you want (but please check
the Apache documentation; getting this right is important for the
security of your website and the privacy of your email):

AuthType Basic
AuthName "Email"
AuthUserFile /path/to/htpasswd
require user your_username_here
DirectoryIndex webmail.cgi
AddHandler cgi-script cgi

For Apache, you'll also need to create the htpasswd file using the
htpasswd program.  (This should be located outside the server's URI
space, for fairly obvious security reasons.)

Now set up the various configuration variables: address of POP and
SMTP servers, etc. etc.  You can either edit the settings in the
webmail.cgi file, or create a separate file (e.g. config.pl) to define
them.  The comments in webmail.cgi describe all this.

This would be a good point to review the security issues.  You have
just put your POP3 password in a text file.  Who can read it?  What
does it give them access to?  The answers should be "only me" and
"only my email".  If you don't fully understand the security issues,
do some background reading before proceeding.

Included in the configuration variables are options to enable and
disable the QWAZERTY keyboard layout translation and the Speller Pages
spell checker.  If you don't what these, switching them off will make
the pages smaller.

If you want to use spell checking you'll need to have aspell installed
on your web server.  If you don't already have it it is fairly
straightforward to install (it is a standard GNU configure / make /
make install procedure).  You can either install it as root or in your
own filespace.  You need to install aspell itself and then one or more
dictionaries.  Whether you already had aspell or have just installed
it, you need to edit spellchecker.cgi to specify the location of the
aspell executable ($aspell_cmd) and the language to use ($lang).

You may need to install extra Perl modules if your server doesn't have
everything.  You may get helpful errors with the name of the missing
module via your web browser if something is missing.  If you can't
install the modules as root, simply put the necessary files in
subdirectories of the directory containing the script.  For example,
if the error message complains about "Mail/POP3Client.pm", create a
directory called Mail and put POP3Client.pm in it.

OK, now see if it works.


Troubleshooting tips
--------------------

(Contributions to this section welcome.)

If the spell check and compose functions don't seem to be working,
make sure that your browser is not configured to prevent popups.

If you want to change the appearance (colours, dimensions etc.), start
by looking at the CSS file.