"Fossies" - the Fresh Open Source Software Archive

Member "roundcubemail-1.4.2/INSTALL" (1 Jan 2020, 12529 Bytes) of package /linux/www/roundcubemail-1.4.2.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "INSTALL": 1.4.1_vs_1.4.2.

    1 INTRODUCTION
    2 ============
    3 
    4 This file describes the basic steps to install Roundcube Webmail on your
    5 web server. For additional information, please also consult the project's
    6 wiki page at https://github.com/roundcube/roundcubemail/wiki
    7 
    8 
    9 REQUIREMENTS
   10 ============
   11 
   12 * An IMAP, HTTP and SMTP server
   13 * .htaccess support allowing overrides for DirectoryIndex
   14 * PHP Version 5.4 or greater including:
   15    - PCRE, DOM, JSON, Session, Sockets, OpenSSL, Mbstring, Filter, Ctype (required)
   16    - PHP PDO with driver for either MySQL, PostgreSQL, SQL Server, Oracle or SQLite (required)
   17    - Iconv, Zip, Fileinfo, Intl, Exif (recommended)
   18    - LDAP for LDAP addressbook support (optional)
   19    - GD, Imagick (optional thumbnails generation, QR-code)
   20 * PEAR and PEAR packages distributed with Roundcube or external:
   21    - Mail_Mime 1.10.0 or newer
   22    - Net_SMTP 1.8.1 or newer
   23    - Net_Socket 1.0.12 or newer
   24    - Net_IDNA2 0.1.1 or newer
   25    - Auth_SASL 1.0.6 or newer
   26    - Net_Sieve 1.4.3 or newer (for managesieve plugin)
   27    - Crypt_GPG 1.6.3 or newer (for enigma plugin)
   28    - Endroid/QrCode 1.6.0 or newer (https://github.com/endroid/QrCode)
   29    - Kolab/Net_LDAP3 1.0.6 or newer (for LDAP addressbook)
   30    - Masterminds/HTML5 2.5.x (optional HTML parser)
   31 * php.ini options:
   32    - error_reporting E_ALL & ~E_NOTICE & ~E_STRICT
   33    - memory_limit > 16MB
   34    - file_uploads enabled (for uploading attachments and import files)
   35    - session.auto_start disabled
   36    - suhosin.session.encrypt disabled
   37    - mbstring.func_overload disabled
   38    - pcre.backtrack_limit >= 100000
   39 * A MySQL, PostgreSQL, MS SQL Server (2005 or newer), Oracle database
   40   or SQLite support in PHP - with permission to create tables
   41 * Composer installed either locally or globally (https://getcomposer.org)
   42 
   43 
   44 INSTALLATION
   45 ============
   46 
   47 1. Decompress and put this folder somewhere inside your document root.
   48   Note: Make sure files have proper owner/group for your setup. If you use
   49   tar command `--no-same-owner` option might be helpful.
   50 2. In case you don't use the so-called "complete" release package,
   51   you have to install PHP and javascript dependencies.
   52   2.1. Install PHP dependencies using composer:
   53     - get composer from https://getcomposer.org/download/
   54     - rename the composer.json-dist file into composer.json
   55     - if you want to use LDAP address books, enable the LDAP libraries in your
   56       composer.json file by moving the items from "suggest" to the "require"
   57       section (remove the explanation texts after the version!).
   58     - run `php composer.phar install --no-dev`
   59   2.2. Install Javascript dependencies by executing `bin/install-jsdeps.sh` script.
   60 3. Make sure that the following directories (and the files within)
   61    are writable by the webserver
   62    - /temp
   63    - /logs
   64 4. Create a new database and a database user for Roundcube (see DATABASE SETUP)
   65 5. Point your browser to http://url-to-roundcube/installer/
   66 6. Follow the instructions of the install script (or see MANUAL CONFIGURATION)
   67 7. After creating and testing the configuration, remove the installer directory
   68 8. If you use git sources compile css files for the Elastic skin (required
   69    lessc >= 1.5.0):
   70    $ cd skins/elastic
   71    $ lessc -x styles/styles.less > styles/styles.css
   72    $ lessc -x styles/print.less > styles/print.css
   73    $ lessc -x styles/embed.less > styles/embed.css
   74 9. Check Known Issues section of this file
   75 
   76 
   77 CONFIGURATION HINTS
   78 ===================
   79 
   80 IMPORTANT! Read all comments in defaults.inc.php, understand them
   81 and configure your installation to be not surprised by default behaviour.
   82 
   83 Roundcube writes internal errors to the 'errors.log' log file located in the logs
   84 directory which can be configured in config/config.inc.php. If you want ordinary
   85 PHP errors to be logged there as well, set error_log in php.ini or .htaccess file.
   86 
   87 Roundcube forces display_errors=Off and log_errors=On.
   88 
   89 By default the session cookie settings of PHP are not modified by Roundcube.
   90 However if you want to limit the session cookies to the directory where
   91 Roundcube resides you can set session.cookie_path in the php.ini or .htaccess file.
   92 
   93 More about PHP settings: https://github.com/roundcube/roundcubemail/wiki/Installation#php-configuration
   94 
   95 
   96 DATABASE SETUP
   97 ==============
   98 
   99 Note: Database for Roundcube must use UTF-8 character set.
  100 Note: See defaults.inc.php file for examples of DSN configuration.
  101 
  102 * MySQL
  103 -------
  104 Setting up the mysql database can be done by creating an empty database,
  105 importing the table layout and granting the proper permissions to the
  106 roundcube user. Here is an example of that procedure:
  107 
  108 # mysql
  109 > CREATE DATABASE roundcubemail /*!40101 CHARACTER SET utf8 COLLATE utf8_general_ci */;
  110 > GRANT ALL PRIVILEGES ON roundcubemail.* TO roundcube@localhost
  111     IDENTIFIED BY 'password';
  112 > quit
  113 
  114 # mysql roundcubemail < SQL/mysql.initial.sql
  115 
  116 Note 1: 'password' is the master password for the roundcube user. It is strongly
  117 recommended you replace this with a more secure password. Please keep in
  118 mind: You need to specify this password later in 'config/db.inc.php'.
  119 
  120 
  121 * SQLite
  122 --------
  123 Versions of sqlite database engine older than 3 aren't supported.
  124 Database file and structure is created automatically by Roundcube.
  125 Make sure your configuration points to some file location and that the
  126 webserver can write to the file and the directory containing the file.
  127 
  128 
  129 * PostgreSQL
  130 ------------
  131 To use Roundcube with PostgreSQL support you have to follow these
  132 simple steps, which have to be done as the postgres system user (or
  133 which ever is the database superuser):
  134 
  135 $ createuser -P roundcube
  136 $ createdb -O roundcube -E UNICODE roundcubemail
  137 $ psql -U roundcube -f SQL/postgres.initial.sql roundcubemail
  138 
  139 Note: in some system configurations you might need to add '-U postgres' to
  140 createuser and createdb commands.
  141 
  142 
  143 * Microsoft SQL Server
  144 ----------------------
  145 Language/locale of the database must be set to us_english (1033). More info
  146 on this at https://github.com/roundcube/roundcubemail/issues/4078.
  147 
  148 
  149 Database cleaning
  150 -----------------
  151 To keep your database slick and clean we recommend to periodically execute
  152 bin/cleandb.sh which finally removes all records that are marked as deleted.
  153 Best solution is to install a cronjob running this script daily.
  154 
  155 
  156 MANUAL CONFIGURATION
  157 ====================
  158 
  159 First of all, copy the sample configuration file config/config.inc.php.sample
  160 to config/config.inc.php and make the necessary adjustments according to your
  161 environment and your needs. More configuration options can be copied from the
  162 config/defaults.inc.php file into your local config.inc.php file as needed.
  163 Read the comments above the individual configuration options to find out what
  164 they do or read https://github.com/roundcube/roundcubemail/wiki/Installation
  165 for even more guidance.
  166 
  167 The maximum size of email attachments and other file uploads is controlled by
  168 PHP settings: upload_max_filesize and post_max_size. Read more about PHP
  169 settings at https://github.com/roundcube/roundcubemail/wiki/Installation#php-configuration.
  170 
  171 
  172 SECURE YOUR INSTALLATION
  173 ========================
  174 
  175 Access through the webserver to the following directories should be denied:
  176 
  177   /config
  178   /temp
  179   /logs
  180 
  181 Roundcube uses .htaccess files to protect these directories, so be sure to
  182 allow override of the Limit directives to get them taken into account. The
  183 package also ships a .htaccess file in the root directory which defines some
  184 rewrite rules. In order to properly secure your installation, please enable
  185 mod_rewrite for Apache webserver and double check access to the above listed
  186 directories and their contents is denied.
  187 
  188 NOTE: In Apache 2.4, support for .htaccess files has been disabled by
  189 default. Therefore you first need to enable this in your Apache main or
  190 virtual host config by with:
  191 
  192   AllowOverride all
  193 
  194 For non-apache web servers add equivalent configuration parameters to deny
  195 direct access to these private resources.
  196 
  197 It is also recommended to change the document root to <install path>/public_html
  198 after installation if Roundcube runs at root of a dedicated virtual host. This
  199 will automatically keep sensitive files out of reach for http requests.
  200 
  201 
  202 UPGRADING
  203 =========
  204 
  205 If you already have a previous version of Roundcube installed,
  206 please refer to the instructions in UPGRADING guide.
  207 
  208 
  209 OPTIMISING
  210 ==========
  211 
  212 There are two forms of optimisation here, compression and caching, both aimed
  213 at increasing an end user's experience using Roundcube Webmail. Compression
  214 allows the static web pages to be delivered with less bandwidth. The index.php
  215 of Roundcube Webmail already enables compression on its output. The settings
  216 below allow compression to occur for all static files. Caching sets HTTP 
  217 response headers that enable a user's web client to understand what is static
  218 and how to cache it.
  219 
  220 The caching directives used are:
  221  * Etags - sets at tag so the client can request is the page has changed
  222  * Cache-control - defines the age of the page and that the page is 'public'
  223    This enables clients to cache javascript files that don't have private 
  224    information between sessions even if using HTTPS. It also allows proxies
  225    to share the same cached page between users.
  226  * Expires - provides another hint to increase the lifetime of static pages.
  227 
  228 For more information refer to RFC 2616.
  229 
  230 Side effects:
  231 -------------
  232 These directives are designed for production use. If you are using this in
  233 a development environment you may get horribly confused if your webclient
  234 is caching stuff that you changed on the server. Disabling the expires 
  235 parts below should save you some grief.
  236 
  237 If you are changing the skins, it is recommended that you copy content to 
  238 a different directory apart from 'default'.
  239 
  240 Apache:
  241 -------
  242 To enable these features in apache the following modules need to be enabled:
  243  * mod_deflate
  244  * mod_expires
  245  * mod_headers
  246 
  247 The optimisation is already included in the .htaccess file in the top 
  248 directory of your installation.
  249 
  250 If you are using Apache version 2.2.9 and later, in the .htaccess file
  251 change the 'append' word to 'merge' for a more correct response. Keeping
  252 as 'append' shouldn't cause any problems though changing to merge will 
  253 eliminate the possibility of duplicate 'public' headers in Cache-control.
  254 
  255 Lighttpd:
  256 ---------
  257 With Lightty the addition of Expire: tags by mod_expire is incompatible with
  258 the addition of "Cache-control: public". Using Cache-control 'public' is 
  259 used below as it is assumed to give a better caching result.
  260 
  261 Enable modules in server.modules:
  262     "mod_setenv"
  263     "mod_compress"
  264 
  265 Mod_compress is a server side cache of compressed files to improve its performance.
  266 
  267 $HTTP["host"] == "www.example.com" {
  268 
  269     static-file.etags = "enable"
  270     # http://redmine.lighttpd.net/projects/lighttpd/wiki/Etag.use-mtimeDetails
  271     etag.use-mtime = "enable"
  272 
  273     # http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ModSetEnv
  274     $HTTP["url"] =~ "^/roundcubemail/(plugins|skins|program)" {
  275         setenv.add-response-header  = ( "Cache-Control" => "public, max-age=2592000")
  276     }
  277 
  278     # http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ModCompress
  279     # set compress.cache-dir to somewhere outside the docroot.
  280     compress.cache-dir   = var.statedir + "/cache/compress"
  281 
  282     compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml", "image/gif", "image/png")
  283 }
  284 
  285 
  286 KNOWN ISSUES
  287 ============
  288 
  289 Installations with uw-imap server should set imap_disabled_caps = array('ESEARCH')
  290 in main configuration file. ESEARCH implementation in this server is broken (#1489184).
  291 
  292 PHP >= 5.6 validates the ssl certificates by default. It means that
  293 if IMAP/SMTP certificates are self-signed or use wrong host name you'll get
  294 connection errors. A solution in such cases is to set imap_conn_options,
  295 smtp_conn_options and managesieve_conn_options in a way described in config/defaults.inc.php.
  296 
  297 If you have problems with temp files or non-working logs make sure temp and logs folders
  298 are writeable to the user used by http server. Access to them may also be blocked by
  299 SELINUX. Here's some sample commands for SELINUX:
  300 
  301     $ semanage fcontext -a -t httpd_sys_rw_content_t "/path_to_roundcube/logs(/.*)?"
  302     $ semanage fcontext -a -t httpd_sys_rw_content_t "/path_to_roundcube/temp(/.*)?"
  303     $ restorecon -Rv /path_to_roundcube/
  304 
  305 Microsoft IIS Server by default does not support WOFF fonts used in Elastic skin. It might be
  306 needed to add following MIME Types definitions (via web.config or IIS Manager):
  307 
  308     .woff   application/font-woff
  309     .woff2  application/font-woff2