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