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