path: root/web/INSTALL

alpine.tar.z web/INSTALL
/* ========================================================================
 * Copyright 2006-2008 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * ========================================================================
 */


BUILDING AND INSTALLING WEB ALPINE
----------------------------------

This file provides brief instructions for building, installing and
configuring the Web Alpine application

Web Alpine's binary components are built along with the other Alpine
Mail System components.  If the build process completed, that is the
commands ./configure and make completed without error, then you are
nearly good to go.

Unlike the other Alpine components, however, Web Alpine does not use
the "make install" method of installation.  Between the various Web
Alpine pieces, web site layout and web server configuration,
variability and administrative preference is too great to be reliably
automated at this time.

For more information on the how's and why's of Web Alpine consult the
somewhat more technically complete treatment in
web/cgi/alpine/help/tech-notes.html.

At some point online FAQs and such may be available.  If you find
anything missing, incomplete, or otherwise unclear please send a note
to <chappa@gmx.com>.


WEB ALPINE LAYOUT
-----------------

The Web Alpine package is distributed as part of the Alpine Mail System.
The source for the various components can be found in the "web/"
directory arranged, for the most part, by function.

  src/
      alpined.d/
       source for Web Alpine's binary components: the
       per-user/per-session serverette and the small library used for
       inter-tcl script communication.

      pubcookie/
        sources for various components required to provide
        pubcookie web-login support

      cgi.tcl-1.10/
        Tcl library used to help coordinate web page generation

  cgi/
    CGI scripts used to generate Web Alpine pages, typically synonymous
    with the web server's document root.  It, in turn, contains:

      alpine/
	Meat and potatoes of the Web Alpine Application.

      alpine-2.0/
	Meat and potatoes of the Web Alpine 2.0 Application

      session/
	Alpine session management scripts used to login, establish
	an alpine session, logout and acquire IMAP server credentials
	as needed.  These scripts are distinct from the alpine/
	scripts in order to properly scope the session key.

      images/
	Various images and icons

      pub/
	Scripts that are accessed outside the scope of the Web Alpine
	session key.

      sounds/
	Sounds files that might be referenced by Web Alpine

  config/
    general Web Alpine and default host configurations

  bin/
    binary executables providing services to the CGI scripts

  lib/
    binary and script routines used by both CGI scripts
    and binary utilities

For a more thorough discussion of the distribution's layout and
Web Alpine components see cgi/alpine/help/tech-notes.html.
  

BUILDING WEB ALPINE'S BINARY COMPONENTS
---------------------------------------

For the most part, Web Alpine's binary components were built
automatically along with the rest of the Alpine Mail System.

If configure reports that it could not locate suitable TCL libraries
and header files, then it is likely that the components necessary for
Web Alpine were not built.  Locating and installing a TCL development
environment appropriate for your system should get the build back on
track.  Note, even though a tclsh interpreter may be available on the
command line, tools necessary to build TCL applications may need to be
installed separately.

If you plan to use UW pubcookie for browser-based network login,
please review src/pubcookie/README.  Be sure the Web Alpine Mail
System was configured with the "--with-pubcookie" AND --with-web-bin=
options set.  The latter is set to the directory that will eventually
contain Web Alpine's binary components.  For the example system
described in the next section, you would add:

    --with-pubcookie --with-web-bin=/usr/local/libexec/alpine/bin

to the configure script's command line.


ACQUIRING EXTERNAL LIBRARIES
----------------------------

Web Alpine 2.0 makes heavy use of the functionality provided by the
The Yahoo! User Interface Library (YUI).  By default, Web Alpine is
configured to generate pages that cause user's browser to request the
necessary library files directly from Yahoo servers.

Web Alpine can be easily configured to generate pages with references
to a local copy of the YUI libraries.  

First, you will need to download the YUI libararies from:

        http://developer.yahoo.com/yui/download/

They are made available to Web Alpine 2.0 scripts thru the symbolic
link:

        web/cgi/alpine-2.0/lib/yui

Simply install the downloaded library in the directory specified by
the symbolic link, or change the link to refer to the intalled
location.

Second, you will need to change the _wp(yui) configuration setting
in

        web/config/alpine.tcl

to reference the new location.


INSTALLING WEB ALPINE COMPONENTS
--------------------------------

Unfortunately, due to the variety of web server requirements and
configurations, Web Alpine installation must be done by hand and
requires several steps.  To illustrate the procedure, a generic Fedora
Core 8 system with standard httpd package installed is used as an
example.  On other systems, the general ideas are the same but the
specific file locations and server configuration settings will likely
vary.  Note also that your system may have an additional security
layer installed, such as selinux, that may require extra configuration
that is beyond the scope of this explanation.

The first step is to build and configure the tools Web Alpine needs to
generate pages and access mail data.  The following commands will put
those tools where they need to be within the web/ directory structure.

  1.  % cd web/src

  2.  % make

  3.  % make install

Second, the web/ directory tree needs to be made available to the web
server.  On the example system, start by moving the web/ directory
tree into a more system-visible location.  We'll also change the name
to reflect the current version number (for this example, 1.00) to help
keep future upgrades isolated.  This command will likely require
elevated privileges using either sudo or after becoming root.

  4.  % cd ../..

  5.  % sudo mv web /usr/local/libexec/alpine-2.00

Next, for simplicity, create a generically named symbolic link as a
synonym for the version-specific directory.

  6.  % cd /usr/local/libexec

  7.  % sudo ln -s alpine-2.00 alpine

After that, make the scripts that actually generate the user visible
portion of Web Alpine available to the web server.

  8.  % cd /var/www

  9.  % sudo ln -s /usr/local/libexec/alpine/cgi ./alpine

Now adjust the web server's configuration so that it can effectively
provide Web Alpine pages to connecting browsers by editing httpd's
configuration file.

 10.  % sudo vi /etc/httpd/conf/httpd.conf

    After the section that starts with <Directory /var/www/html> and ends
    with </Directory>, add the lines:

      #
      # This sets up Web Alpine
      #
      <Directory "/var/www/alpine">
          Options FollowSymLinks ExecCGI -Indexes
          AllowOverride All
          Order allow,deny
          Allow from all
      </Directory>

If you intend for your web server to provide Web Alpine pages
exclusively, then simply edit the DocumentRoot to the directory
defined above:

      DocumentRoot /var/www/alpine

If your web server offers pages other than Web Alpine, specify a
prefix the web server should use for referencing Web Alpine pages by
adding this line before the <Directory> entry specified above:

      Alias /webmail/ "/var/www/alpine/"

After saving httpd.conf with these small additions, it's time to
adjust Web Alpine's configuration.

First, be sure the symbolic link "/usr/local/libexec/alpine/bin/tclsh"
points to the tclsh interpreter for your system.  The default should
work for the example system.

Then edit the Web Alpine configuration file to configure appropriate
settings for your environment.

 11.  % sudo vi /usr/local/libexec/alpine/config/alpine.tcl

    The config file is itself a Tcl script, and the settings are
    simply Tcl variable settings.  Most are settings of elements
    within the "_wp" array.

    Starting from the top, skim the various configuration
    settings.  The primary one's to be aware of include:

          admin      email address offered in error pages
                     associated with problems that likely
                     require system administrator attention

          helpdesk   email address offered in help pages and
                     some error pages as a place to report
                     problems or get more information

          comments   email address offered in help pages
                     as place to send general comments on
                     web alpine

          urlprefix  directory or path defined in the httpd.conf's
                     "Alias" setting.  In example above, set this to
                     "webmail".  If DocumentRoot set as above, set this
		     to {}.

          fileroot   file system path to directory that contains cgi/,
                     config/, bin/, and lib/ directories.  In example
                     above, set this to /usr/local/libexec/alpine.

    Continue scanning the list, and adjust as needed.  Most defaults
    should be fine.  Until you come to:

          ispell     full path to ispell application if installed

          ssl_safe_domains
                     a performance setting that allows for relatively 
                     safe disabling of SSL for connections that we know
                     are reasonably safe from sniffing.  For our campus
                     web alpine installation, browsers associated with the
                     campus dial-in pools connecting to our servers
                     offer this kind of connection.  Be careful.

          flexserver 
                     determines whether or not web alpine offers the option
                     of connecting to a user-defined IMAP server on
                     the greeting page.

          hosts      an array of default configurations that 
                     correspond to default web alpine config files
                     in the config/ directory. these are what
                     is offered on the greeting page as the option
                     list of servers to connect to.

       And, probably lastly:

          cgi_mail_relay
                     the server used to send out script errors that are
                     so heinous that no web page error could be generated


The final step is to restart httpd and give it a try!  Using a browser
pointed to your server's https port, try connecting to the alpine/
directory.

If you run into problems, rest assured you have our sympathies.
Because of the various components that must be coordinated, errors can
be difficult to resolve.  The good news is, once initially configured
and working the system is reasonably stable.  As for debugging, with
luck, the error response reported in the browser will point in a
useful direction. If not, check httpd access and error logs to verify
paths and check for exceptional conditions.  Next, check syslog's
maillog for any exceptional reports issued by the alpined serverette.
Depending on the type of error, you may also have to consult the IMAP
server's logs for clues.


COLLECTED GOTCHAS AND SO FORTH
------------------------------

First, it is strongly encourage that Web Alpine be run on a web server
that does not have general user accounts.  The primary reason is to
maintain the privacy of the Web Alpine session key.  Steps are taken
to minimize the risk and consequences of session key exposure, but
there are risks nonetheless.

For the most part, the default Web Alpine application settings should
require little adjustment for your particular environment.  These
settings are in the web/config/pine.conf file which uses the same
format as alpine's pinerc file.  The most likely setting to adjust is
"smtp-server."

By default, Web Alpine sends via SMTP to the localhost's SMTP port.
This setting can easily be adjusted by setting the smtp-server in
web/config/pine.conf to one or more external servers.  Web Alpine can
also be directed to post to a local process by setting the
sendmail-path variable.  Be aware, however, posting to a local process
(e.g., sendmail, postfix, etc), will likely require you to grant
trusted mail user privilege to the userid associated with the web
server process.  Without such privilege, the SMTP envelope From will
be set to the web server's userid which causes all externally bounced
mail to be returned to the mailbox associated with the web server
userid.


FURTHER INFORMATION
-------------------

See the Web Alpine technical notes for more detailed descriptions of
what's going on and why.  If you have any questions or comments drop
us a note <chappa@gmx.com>.