Initial Alpine Version

1 files changed, 361 insertions, 0 deletions

diff --git a/web/INSTALL b/web/INSTALL
new file mode 100644
index 00000000..62ce69d6
--- /dev/null
+++ b/web/INSTALL
@@ -0,0 +1,361 @@
+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 <alpine-contact@cac.washington.edu>.
+
+
+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 aquire 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 configuation 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 <alpine-contact@cac.washington.edu>.
+
+-- 
+$Id: INSTALL 1169 2008-08-27 06:42:06Z hubert@u.washington.edu $