moving functions to separate file, adding configuration files
[squirrelmail.git] / INSTALL
1 Installing SquirrelMail
2 =======================
3
4 Table of Contents:
5   0.  (QUICK!)   Quick install guide
6   1.  (PHP4)     Configure your webserver to work with PHP4
7   2.  (IMAP)     Setting up IMAP (not covered)
8   3.  (INSTALL)  Obtaining and installing SquirrelMail
9   4.  (RUN)      Running SquirrelMail
10   5.  (CHARSETS) Russian Charsets
11   6.  (LOCALES)  Translations of SquirrelMail
12
13
14 0. QUICK INSTALL GUIDE
15 ----------------------
16
17 Each of these steps is covered in detail below.
18
19 - Install webserver and PHP4 (at least 4.1.0).
20 - Install IMAP server (see docs of that server).
21 - Unpack the SquirrelMail package in a web-accessible location.
22 - Select a data-dir and attachment dir, outside the webtree (e.g. in /var).
23   The data-dir (for user prefs) should be owned by the user the webserver
24   runs as (eg www-data). The attachment dir (for uploading files as
25   attachments) should be file mode 0730 and in the same group as the
26   webserver.
27 - Run config/conf.pl from the command line. Use the D option to load
28   predefined options for specific IMAP servers, and edit at least the
29   Server Settings and General Options (datadir).
30 - Browse to http://www.example.com/yourwebmaillocation/src/configtest.php
31   to test your configuration for common errors.
32 - Browse to http://www.example.com/yourwebmaillocation/ to log in.
33
34
35 1. CONFIGURE YOUR WEBSERVER TO WORK WITH PHP4
36 ---------------------------------------------
37
38   If your webserver does not already have PHP you must configure it
39   to work with PHP. You need at least PHP v4.1.0. SquirrelMail uses
40   the standard suffix .php for all PHP4 files.
41   
42   You can find PHP at http://www.php.net. See the documentation that
43   comes with PHP for instructions how to set it up.
44
45   The PHP IMAP extension is NOT neccessary at all (but won't harm)!
46   Below is a list of optional PHP extensions:
47
48   --with-ldap     Required for LDAP addressbooks
49   --with-mhash    Will improve charset decoding if present
50   --with-mysql    For MySQL storage of preferences or addressbooks
51   --with-openssl  When you want to use encrypted IMAP connections (TLS)
52   
53   If you're going to use LDAP in the addressbook, you must compile PHP
54   with the LDAP extension. Include the MHASH extension to improve
55   performance in character set decoding.
56
57   If you want your users to attach files to their mails, make sure
58   File Uploads in php.ini is set to On.
59
60
61 2. SETTING UP IMAP
62 ------------------
63
64   This depends a lot on the server your choose. See the documentation
65   that comes with your server.
66   
67   If you're concerned about people accessing it directly, you can
68   limit access to only the IP of the webserver.
69
70
71 3. OBTAINING AND INSTALLING SQUIRRELMAIL
72 ----------------------------------------
73
74   SquirrelMail is constantly being improved. Therefore you should always
75   get the newest version around. Look at http://www.squirrelmail.org
76   to see what it is. If you want to be bleeding edge you might want to
77   consider using the latest CVS version (with the latest and most
78   fashionable bugs).
79
80 a. Download SquirrelMail
81
82   Get SquirrelMail from the address above if you do not have it or are
83   uncertain if you have the newest version. Untar (again tar xvfz
84   filename.tgz) SquirrelMail in a directory that is readable for your
85   webserver.
86
87 b. Setting up directories
88
89   SquirrelMail uses two directories to store user configuration and
90   attachments that are about to be sent. You might want to have these
91   directories outside of your web tree.
92
93   The data directory is used for storing user preferences, like
94   signature, name and theme. When unpacking the sources this directory
95   is created as data/ in your SquirrelMail directory. This directory
96   must be writable by the webserver. If your webserver is running as
97   the user "nobody" you can fix this by running:
98
99     $ chown -R nobody data
100     $ chgrp -R nobody data
101
102   Keep in mind that with different installations, the web server could
103   typically run as userid/groupid of nobody/nobody, nobody/nogroup, 
104   apache/apache or www-data/www-data.  The best way to find out is to read 
105   the web server's configuration file.
106
107   There also needs to be a directory where attachments are stored
108   before they are sent. Since personal mail is stored in this
109   directory you might want to be a bit careful about how you set it
110   up. It should be owned by another user than the webserver is running
111   as (root might be a good choice) and the webserver should have write
112   and execute permissions on the directory, but should not have read
113   permissions. You could do this by running these commands (still
114   granted that the webserver is running as nobody/nobody)
115
116     $ cd /var/some/place
117     $ mkdir SomeDirectory
118     $ chgrp -R nobody SomeDirectory
119     $ chmod 730 SomeDirectory
120
121   If you trust all the users on you system not to read mail they are
122   not supposed to read change the last line to chmod 777 SomeDirectory
123   or simply use /tmp as you attachments directory. 
124   
125   If a user is aborting a mail but has uploaded some attachments to it 
126   the files will be lying around in this directory forever if you do not 
127   remove them.  To fix this, it is recommended to create a cron job that
128   deletes everything in the attachment directory.  Something similar
129   to the following will be good enough:
130
131     $ cd /var/attach/directory
132     $ rm -f *
133     
134   However, this will delete attachments that are currently in use by people
135   sending email when the cron job runs.  You can either (1) make sure that
136   the cron job runs at an obscure hour and hope that nobody gets upset, or
137   (2) you can run a modified version of the commands above.  Check out the
138   man pages for other commands such as 'find' or 'tmpreaper'.
139   
140   One sample script you could set up that would erase all attachments, but
141   wouldn't erase preferences, address books, or the like (just in case your
142   attachment directory is the same as your data directory) might look like 
143   this:
144    
145     $ rm `find /var/attach/directory -atime +2 | grep -v "\." | grep -v _`
146     
147   Remember to be careful with whatever method you do use, and to test out
148   the command before it potentially wipes out everyone's preferences.
149
150 c. Setting up SquirrelMail
151
152   There are two ways to configure SquirrelMail.  In the config/ directory,
153   there is a perl script called conf.pl that will aid you in the
154   configuration process.  This is the recommended way of handling
155   the config.
156
157   You can also copy the config/config_default.php file to config/config.php
158   and edit that manually.
159
160   After you've created a configuration, you can use your webbrowser to
161   browse to http://your-squirrelmail-location/src/configtest.php.
162   This will perform some basic checks on your config to make sure
163   everything works like it should.
164
165
166 4. RUNNING SQUIRRELMAIL
167 -----------------------
168
169   Point your browser at the URL at which SquirrelMail is installed.  A
170   possible example of this is: 
171      http://www.yourdomain.com/squirrelmail
172      
173   It should be pretty straight forward to use. Some more documentation
174   might show up one day or another.
175
176
177 5. RUSSIAN CHARSETS
178 -------------------
179
180   For information on how to make SquirrelMail work with Russian
181   Apache, see the README.russian_apache in the doc/ subdirectory.
182
183
184 6. TRANSLATIONS
185 ---------------
186
187   In order to use translated versions of SquirrelMail, you need 
188   to download and install locale packages that contain translations
189   that you want to use with squirrelmail.
190   
191   Locale packages can be downloaded from SquirrelMail SourceForge
192   project page.
193   
194   http://sourceforge.net/project/showfiles.php?group_id=311&package_id=110388
195   
196   Each translation contains install script that copies required files
197   into appropriate locations. If you can't run that script, you can extract
198   contents of translation packages into your squirrelmail directory.
199   
200   NOTE No.1: *-src.tar.gz, *-src.tar.bz2 and *-src.zip archives does not contain
201   compiled translation files. You will need to run compilelocales script
202   in order to get all gettext binary translations.
203   
204   NOTE No.2: You might need to restart your webserver before using translations.
205   If you can't do that, install your translations _before_ you use SquirrelMail.