diff options
Diffstat (limited to 'web/INSTALL')
| -rw-r--r-- | web/INSTALL | 361 |
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 $ |