File: INSTALL

package info (click to toggle)
alpine 1.10%2Bdfsg-3
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 26,036 kB
  • ctags: 21,767
  • sloc: ansic: 308,814; tcl: 19,749; sh: 9,822; makefile: 1,926; perl: 189; exp: 69; csh: 48; sed: 16
file content (326 lines) | stat: -rw-r--r-- 12,404 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
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.

      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.


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-1.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-1.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 .

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 below 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 906 2008-01-11 19:15:07Z mikes@u.washington.edu $