* Updated docs to tell the user to read any documentation that came with the
[squirrelmail.git] / UPGRADE
1 Upgrading from 0.3 or higher 
2 ============================
3
4 If you are upgrading from versions 0.3 or higher of SquirrelMail, you can
5 use this guide to make the transition a bit smoother.  If you have been
6 using a previous version (0.1 or 0.2), it is suggested that you just start
7 from scratch and configure your settings as if it was your first install.
8
9 NOTE: The new plugin architecture required the use of some functions which
10 are not in all versions of PHP4. You will need at least PHP4 beta2. If you
11 need to upgrade please go ahead and install the latest release version of
12 PHP4.
13
14
15 1.  Backup old install
16 ======================
17
18 Make a backup of your current SquirrelMail directory.  If you use "cp", be
19 sure to use the "-Rp" options.  -R means recursive, and -p will save the
20 permissions in the directory.
21
22 In this example, we assume that your httpd document directory is 
23 /home/httpd/html, that your SquirrelMail install is located at
24 /home/httpd/html/squirrelmail-0.4, and that your new SM version is 0.5.
25 Substitute version numbers and names as required.
26
27   $ cd /home/httpd/html
28   $ cp -Rp squirrelmail-0.4 squirrelmail-0.4.bak
29
30
31 2.  Unarchive new SquirrelMail
32 ==============================
33 Make sure that you are in your httpd document directory (/home/httpd/html)
34 and then unarchive the SquirrelMail archive (whatever the filename is): 
35
36   $ tar -zxvf squirrelmail-0.5.tar.gz
37
38
39 3.  Copy important files from old install
40 =========================================
41 The important files to copy are:
42   A.  Preferences
43   B.  Config details
44   C.  Plugins
45   D.  Themes (if you've edited or added any of them)
46   
47 A.  Preferences
48
49 First, copy your preference data over to the new directory.  Usually this is
50 ok, but if you are upgrading from to 1.0.5 or later from anything less than
51 1.0.5, we strongly suggest you let your users reset their preferences.
52 There were important security upgrades in 1.0.5 regarding preference files.
53   
54   $ cp squirrelmail-0.4.bak/data/* squirrelmail-0.5/data
55   
56 B.  Config details
57
58 If at all possible, start the configuration process from scratch.  It is 
59 much less prone to missing configuration options than copying your old
60 configuration.  Ideally, you should just run conf.pl to reconfigure
61 SquirrelMail.  If you decide to copy your old config.php over, we strongly
62 recommend that you run conf.pl to make sure things are correct and then save
63 the config file.
64
65   $ cp squirrelmail-0.4.bak/config/config.php squirrelmail-0.5/config
66
67 C.  Copy plugins
68
69 Like SquirrelMail, plugins are fequently updated for improvements, as well
70 as to make them compatible with new SquirrelMail releases.  It is suggested
71 that you download a new plugins archive at the same time you download your
72 SquirrelMail install, and that you install your plugins fresh (it's easy,
73 don't panic!).
74
75 If you prefer to just copy your old plugins over (if it's the same version
76 or if you are lazy), you may do so.  If you notice irregularities with the
77 plugins under the new SquirrelMail, try installing new versions of the
78 plugins.
79
80   $ cp -Rp squirrelmail-0.4.bak/plugins/* squirrelmail-0.5/plugins
81   
82 D.  Copy themes
83
84 If you've created or modified themes, you should copy just those to the new
85 SquirrelMail themes direcory.  To just copy them all over to the new
86 SquirrelMail installation, you can run one command.
87
88   $ cp squirrelmail-0.4.bak/themes/* squirrelmail-0.5/themes/
89
90 (While you are at it, you should send them to us!  We might add them to the
91 themes in the standard install!)
92
93
94 4.  Change permissions
95 ======================
96 The web server must have write permission to the data directory.  In this
97 example, we assume that user "nobody" and group "nobody" are the web server
98 as is often the case with Apache.
99
100   $ cd squirrelmail-0.5
101   $ chown -R nobody.nobody data
102   
103 See INSTALL for alternate userid/groupid pairs.  Additionally, if "chown
104 user.group" doesn't work, you can use "chown user" and "chgrp group"
105 instead.  See the man pages for these commands for more information.
106
107
108 5.  Run conf.pl
109 ===============
110 Run config/conf.pl to see the new configuration options available with the
111 new version, as well as to verify that all of your old options are set
112 properly.
113
114
115 6.  DONE!
116 =========
117 That should be all!  The most important part is copying your users'
118 preference files back into the new data directory.  This will insure that
119 your users will have their old preferences.  Remember to do so with caution,
120 especially if you are upgrading from a version before 1.0.5 to version 1.0.5
121 or later.