commit | author | age
|
a89845
|
1 |
INTRODUCTION |
T |
2 |
============ |
|
3 |
|
e019f2
|
4 |
This file describes the basic steps to install Roundcube Webmail on your |
a89845
|
5 |
web server. For additional information, please also consult the project's |
83ce4b
|
6 |
wiki page at http://trac.roundcube.net/wiki |
T |
7 |
|
4e17e6
|
8 |
|
535da2
|
9 |
REQUIREMENTS |
T |
10 |
============ |
|
11 |
|
5d62d9
|
12 |
* The Apache, Lighttpd, Cherokee or Hiawatha web server |
535da2
|
13 |
* .htaccess support allowing overrides for DirectoryIndex |
d36115
|
14 |
* PHP Version 5.2.1 or greater including |
a84efc
|
15 |
- PCRE, DOM, JSON, XML, Session, Sockets (required) |
TB |
16 |
- PHP Data Objects (PDO) with driver for either MySQL, PostgreSQL or SQLite (required) |
738996
|
17 |
Note: MySQL database driver requires PHP 5.3 or newer. |
a84efc
|
18 |
- Libiconv, Zip (recommended) |
TB |
19 |
- Fileinfo, Mcrypt, mbstring (optional) |
91790e
|
20 |
* PEAR packages distributed with Roundcube or external: |
53604a
|
21 |
- Mail_Mime 1.8.1 or newer |
77c779
|
22 |
- Mail_mimeDecode 1.5.5 or newer |
c4a226
|
23 |
- Net_SMTP (latest from https://github.com/pear/Net_SMTP/) |
50d7d3
|
24 |
- Net_IDNA2 0.1.1 or newer |
114cf1
|
25 |
- Auth_SASL 1.0.6 or newer |
7d3406
|
26 |
* php.ini options (see .htaccess file): |
535da2
|
27 |
- error_reporting E_ALL & ~E_NOTICE (or lower) |
29640b
|
28 |
- memory_limit > 16MB (increase as suitable to support large attachments) |
067763
|
29 |
- file_uploads enabled (for attachment upload features) |
A |
30 |
- session.auto_start disabled |
|
31 |
- zend.ze1_compatibility_mode disabled |
7d3406
|
32 |
- suhosin.session.encrypt disabled |
A |
33 |
- mbstring.func_overload disabled |
140abb
|
34 |
- magic_quotes_runtime disabled |
0b6d02
|
35 |
- magic_quotes_sybase disabled |
3a01c3
|
36 |
* PHP compiled with OpenSSL to connect to IMAPS and to use the spell checker |
94fe9c
|
37 |
* A MySQL (4.0.8 or newer), PostgreSQL, MSSQL database engine |
d239ee
|
38 |
or SQLite support in PHP |
1fb2c8
|
39 |
* One of the above databases with permission to create tables |
7d3406
|
40 |
* An SMTP server (recommended) or PHP configured for mail delivery |
535da2
|
41 |
|
T |
42 |
|
4e17e6
|
43 |
INSTALLATION |
T |
44 |
============ |
|
45 |
|
|
46 |
1. Decompress and put this folder somewhere inside your document root |
10a699
|
47 |
2. Make sure that the following directories (and the files within) |
T |
48 |
are writable by the webserver |
4e17e6
|
49 |
- /temp |
T |
50 |
- /logs |
e019f2
|
51 |
3. Create a new database and a database user for Roundcube (see DATABASE SETUP) |
967b34
|
52 |
4. Point your browser to http://url-to-roundcube/installer/ |
b8ae99
|
53 |
5. Follow the instructions of the install script (or see MANUAL CONFIGURATION) |
190e97
|
54 |
6. After creating and testing the configuration, remove the installer directory |
42b113
|
55 |
7. Done! |
T |
56 |
|
|
57 |
|
4b20e2
|
58 |
CONFIGURATION HINTS |
T |
59 |
=================== |
|
60 |
|
233622
|
61 |
Roundcube writes internal errors to the 'errors' log file located in the logs |
4b20e2
|
62 |
directory which can be configured in config/main.inc.php. If you want ordinary |
T |
63 |
PHP errors to be logged there as well, enable the 'php_value error_log' line |
|
64 |
in the .htaccess file and set the path to the log file accordingly. |
|
65 |
|
29640b
|
66 |
By default the session_path settings of PHP are not modified by Roundcube. |
T |
67 |
However if you want to limit the session cookies to the directory where |
|
68 |
Roundcube resides you can uncomment and configure the according line |
|
69 |
in the .htaccess file. |
|
70 |
|
4b20e2
|
71 |
|
10a699
|
72 |
DATABASE SETUP |
T |
73 |
============== |
|
74 |
|
233622
|
75 |
Note: Database for Roundcube must use UTF-8 character set. |
0ba548
|
76 |
|
fa898a
|
77 |
* MySQL |
T |
78 |
------- |
10a699
|
79 |
Setting up the mysql database can be done by creating an empty database, |
T |
80 |
importing the table layout and granting the proper permissions to the |
|
81 |
roundcube user. Here is an example of that procedure: |
|
82 |
|
|
83 |
# mysql |
ad5600
|
84 |
> CREATE DATABASE roundcubemail /*!40101 CHARACTER SET utf8 COLLATE utf8_general_ci */; |
10a699
|
85 |
> GRANT ALL PRIVILEGES ON roundcubemail.* TO roundcube@localhost |
6ae6e4
|
86 |
IDENTIFIED BY 'password'; |
10a699
|
87 |
> quit |
fa898a
|
88 |
|
10a699
|
89 |
# mysql roundcubemail < SQL/mysql.initial.sql |
535da2
|
90 |
|
fa898a
|
91 |
Note 1: 'password' is the master password for the roundcube user. It is strongly |
3cf664
|
92 |
recommended you replace this with a more secure password. Please keep in |
T |
93 |
mind: You need to specify this password later in 'config/db.inc.php'. |
fa898a
|
94 |
|
1cded8
|
95 |
|
10a699
|
96 |
* SQLite |
T |
97 |
-------- |
50d515
|
98 |
You need sqlite 2 (preferably 2.8) to setup the sqlite db |
A |
99 |
(sqlite 3.x also doesn't work at the moment). Here is |
10a699
|
100 |
an example how you can setup the sqlite.db for roundcube: |
T |
101 |
|
|
102 |
# sqlite -init SQL/sqlite.initial.sql sqlite.db |
d7f49d
|
103 |
Loading resources from SQL/sqlite.initial.sql |
T |
104 |
SQLite version 2.8.16 |
|
105 |
Enter ".help" for instructions |
|
106 |
sqlite> .exit |
|
107 |
# chmod o+rw sqlite.db |
10a699
|
108 |
|
T |
109 |
Make sure your configuration points to the sqlite.db file and that the |
83ce4b
|
110 |
webserver can write to the file and the directory containing the file. |
10a699
|
111 |
|
T |
112 |
|
1cded8
|
113 |
* PostgreSQL |
T |
114 |
------------ |
233622
|
115 |
To use Roundcube with PostgreSQL support you have to follow these |
a89845
|
116 |
simple steps, which have to be done as the postgres system user (or |
1cded8
|
117 |
which ever is the database superuser): |
T |
118 |
|
a89845
|
119 |
$ createuser roundcube |
ad5600
|
120 |
$ createdb -O roundcube -E UNICODE roundcubemail |
1cded8
|
121 |
$ psql roundcubemail |
T |
122 |
|
|
123 |
roundcubemail =# ALTER USER roundcube WITH PASSWORD 'the_new_password'; |
a89845
|
124 |
roundcubemail =# \c - roundcube |
1cded8
|
125 |
roundcubemail => \i SQL/postgres.initial.sql |
T |
126 |
|
a89845
|
127 |
All this has been tested with PostgreSQL 8.x and 7.4.x. Older |
1cded8
|
128 |
versions don't have a -O option for the createdb, so if you are |
T |
129 |
using that version you'll have to change ownership of the DB later. |
233622
|
130 |
|
T |
131 |
|
|
132 |
Database cleaning |
|
133 |
----------------- |
|
134 |
Do keep your database slick and clean we recommend to periodically execute |
30aa4c
|
135 |
bin/cleandb.sh which finally removes all records that are marked as deleted. |
233622
|
136 |
Best solution is to install a cronjob running this script daily. |
T |
137 |
|
1cded8
|
138 |
|
T |
139 |
|
190e97
|
140 |
MANUAL CONFIGURATION |
T |
141 |
==================== |
535da2
|
142 |
|
a89845
|
143 |
First of all, rename the files config/*.inc.php.dist to config/*.inc.php. |
T |
144 |
You can then change these files according to your environment and your needs. |
|
145 |
Details about the config parameters can be found in the config files. |
190e97
|
146 |
See http://trac.roundcube.net/wiki/Howto_Install for even more guidance. |
535da2
|
147 |
|
4b9efb
|
148 |
You can also modify the default .htaccess file. This is necessary to |
S |
149 |
increase the allowed size of file attachments, for example: |
|
150 |
php_value upload_max_filesize 2M |
535da2
|
151 |
|
83ce4b
|
152 |
|
42b113
|
153 |
UPGRADING |
T |
154 |
========= |
6ae6e4
|
155 |
|
233622
|
156 |
If you already have a previous version of Roundcube installed, |
42b113
|
157 |
please refer to the instructions in UPGRADING guide. |
4e17e6
|
158 |
|
T |
159 |
|
d7f49d
|
160 |
OPTIMISING |
T |
161 |
========== |
|
162 |
|
|
163 |
There are two forms of optimisation here, compression and caching, both aimed |
233622
|
164 |
at increasing an end user's experience using Roundcube Webmail. Compression |
d7f49d
|
165 |
allows the static web pages to be delivered with less bandwidth. The index.php |
233622
|
166 |
of Roundcube Webmail already enables compression on its output. The settings |
d7f49d
|
167 |
below allow compression to occur for all static files. Caching sets HTTP |
T |
168 |
response headers that enable a user's web client to understand what is static |
|
169 |
and how to cache it. |
|
170 |
|
|
171 |
The caching directives used are: |
|
172 |
* Etags - sets at tag so the client can request is the page has changed |
|
173 |
* Cache-control - defines the age of the page and that the page is 'public' |
|
174 |
This enables clients to cache javascript files that don't have private |
|
175 |
information between sessions even if using HTTPS. It also allows proxies |
|
176 |
to share the same cached page between users. |
|
177 |
* Expires - provides another hint to increase the lifetime of static pages. |
|
178 |
|
|
179 |
For more information refer to RFC 2616. |
|
180 |
|
|
181 |
Side effects: |
|
182 |
------------- |
|
183 |
These directives are designed for production use. If you are using this in |
|
184 |
a development environment you may get horribly confused if your webclient |
|
185 |
is caching stuff that you changed on the server. Disabling the expires |
|
186 |
parts below should save you some grief. |
|
187 |
|
|
188 |
If you are changing the skins, it is recommended that you copy content to |
|
189 |
a different directory apart from 'default'. |
|
190 |
|
|
191 |
Apache: |
|
192 |
------- |
|
193 |
To enable these features in apache the following modules need to be enabled: |
a5c2ad
|
194 |
* mod_deflate |
A |
195 |
* mod_expires |
d7f49d
|
196 |
* mod_headers |
T |
197 |
|
|
198 |
The optimisation is already included in the .htaccess file in the top |
|
199 |
directory of your installation. |
|
200 |
|
|
201 |
If you are using Apache version 2.2.9 and later, in the .htaccess file |
|
202 |
change the 'append' word to 'merge' for a more correct response. Keeping |
|
203 |
as 'append' shouldn't cause any problems though changing to merge will |
|
204 |
eliminate the possibility of duplicate 'public' headers in Cache-control. |
|
205 |
|
|
206 |
Lighttpd: |
|
207 |
--------- |
|
208 |
With Lightty the addition of Expire: tags by mod_expire is incompatible with |
|
209 |
the addition of "Cache-control: public". Using Cache-control 'public' is |
|
210 |
used below as it is assumed to give a better caching result. |
|
211 |
|
|
212 |
Enable modules in server.modules: |
|
213 |
"mod_setenv" |
|
214 |
"mod_compress" |
|
215 |
|
|
216 |
Mod_compress is a server side cache of compressed files to improve its performance. |
|
217 |
|
|
218 |
$HTTP["host"] == "www.example.com" { |
|
219 |
|
|
220 |
static-file.etags = "enable" |
|
221 |
# http://redmine.lighttpd.net/projects/lighttpd/wiki/Etag.use-mtimeDetails |
|
222 |
etag.use-mtime = "enable" |
|
223 |
|
|
224 |
# http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ModSetEnv |
|
225 |
$HTTP["url"] =~ "^/roundcubemail/(plugins|skins|program)" { |
|
226 |
setenv.add-response-header = ( "Cache-Control" => "public, max-age=2592000") |
|
227 |
} |
|
228 |
|
|
229 |
# http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ModCompress |
|
230 |
# set compress.cache-dir to somewhere outside the docroot. |
|
231 |
compress.cache-dir = var.statedir + "/cache/compress" |
|
232 |
|
|
233 |
compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml", "image/gif", "image/png") |
|
234 |
} |
|
235 |
|
|
236 |
|