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 . 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 and ends with , add the lines: # # This sets up Web Alpine # Options FollowSymLinks ExecCGI -Indexes AllowOverride All Order allow,deny Allow from all 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 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 .