INSTALL.md

   1 INSTALLING TYPO3
   2 ================
   3
   4 TYPO3 is an open source PHP based web content management system released
   5 under the GNU GPL. TYPO3 is copyright (c) 1999-2015 by Kasper Skaarhoj.
   6
   7 This document describes:
   8
   9 * System requirements for TYPO3
  10 * Installation routine
  11 * Upgrade routine
  12
  13 Client browser support
  14 ----------------------
  15
  16 The TYPO3 backend is accessed through a web browser. TYPO3 CMS 7
  17 supports the following web browsers:
  18
  19 * Internet Explorer 9 and later
  20 * Google Chrome (Windows, MacOS, Linux)
  21 * Firefox (Windows, MacOS, Linux)
  22 * Safari on MacOS
  23 * and other compatible modern browsers
  24
  25 Server system requirements
  26 --------------------------
  27
  28 TYPO3 requires a web server with a PHP environment and a database. The minimum
  29 system requirements for running TYPO3 CMS 7 are:
  30
  31 * Webserver capable of running PHP applications (Apache, Nginx, IIS or other)
  32 * PHP 5.5 up to 7
  33 * MySQL 5.5 up to 5.6 or compatible (no "strict mode", see below)
  34 * more than 200 MB of disk space
  35
  36 Note: If you use any other webserver than Apache, make sure you add the necessary configuration normally
  37 provided in the various `.htaccess` files inside the TYPO3 core. This configuration is security relevant,
  38 therefore only experienced server administrators should create such configuration.
  39
  40 ### MySQL environment
  41
  42 TYPO3 works with MySQL in the above mentioned versions. It will also work on
  43 compatible "drop-in" replacements like MariaDB or Percona.
  44
  45 Note that MySQL "strict mode" is currently not supported by TYPO3. If your
  46 MySQL server is configured with either STRICT_TRANS_TABLES or
  47 STRICT_ALL_TABLES (especially true with MySQL 5.6, as this is a new default),
  48 you need to configure setDBinit in the Install Tool. See question 2 in the
  49 "Installation FAQ" below for more information.
  50
  51 ### MySQL required privileges
  52
  53 The MySQL user needs a least the following privileges on the TYPO3 database:
  54
  55 * SELECT, INSERT, UPDATE, DELETE
  56 * CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES
  57
  58 It is recommended to also grant the following privileges:
  59
  60 * CREATE VIEW, SHOW VIEW
  61 * EXECUTE, CREATE ROUTINE, ALTER ROUTINE
  62
  63 ### PHP environment
  64
  65 * memory_limit set to at least 64M
  66 * max_execution_time set to at least 30s (240s recommended)
  67 * register_globals disabled
  68 * AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
  69   (see FAQ below)
  70
  71 ### PHP required extensions
  72
  73 Your PHP needs to support the following extensions. Install will
  74 check if these are available.
  75
  76 * These are usually part of the standard PHP package on most distributions:
  77   * fileinfo
  78   * filter
  79   * hash
  80   * openssl
  81   * pcre >= 8.30
  82   * session
  83   * soap
  84   * SPL
  85   * standard
  86   * xml
  87   * zip
  88   * zlib
  89
  90 * These might have to be installed separately:
  91   * gd
  92   * json
  93   * mysqli
  94
  95 ### Recommended setup
  96
  97 There are plenty of possible setups for high performance TYPO3 installations
  98 (i.e. using Varnish Cache, Nginx, PHP-FPM, etc). Consider this resource for
  99 more ideas or suggestions:  http://wiki.typo3.org/Performance_tuning
 100
 101 This is a basic recommended setup for best performance and increased
 102 functionality:
 103
 104 * Apache with mod_expires and mod_rewrite enabled
 105
 106 * MySQL 5.5 or newer
 107
 108 * GraphicsMagick or ImageMagick v6 or newer installed on the server
 109
 110 * PHP
 111   * version 5.5 or later
 112   * memory_limit set to at least 128M
 113   * max_execution_time set to at least 240s
 114   * max_input_vars set to at least 1500
 115   * always_populate_raw_post_data set to -1 (PHP version >= 5.6, <7.0)
 116
 117 * Additional PHP extensions:
 118   * PHP opcode cache, i.e.: apc, xcache, eaccelerator, Zend Optimizer, wincache (in case of an IIS installation)
 119   * apcu caching (with at least 100 MB of memory available)
 120   * curl
 121   * mbstring
 122   * FreeType 2 (usually included within the PHP distribution)
 123   * bcmath or gmp (needed if you'd like to use the openid system extension)
 124
 125 * PHP access to /dev/urandom or /dev/random on Unix-like platforms for
 126   increased security. Make sure to add "/dev/random:/dev/urandom" to
 127   open_basedir settings if you use it. If these paths are unavailable, TYPO3
 128   will attempt to simulate random number generation. This is less secure,
 129   reduces performance and throws out warnings in the TYPO3 system log.
 130
 131 * TYPO3 works with PHP's IPv6 support, which is enabled by default.
 132   If you compile PHP on your own, be aware not to use option "--disable-ipv6",
 133   because this will break the IPv6 support and the according unit tests.
 134
 135 Installation
 136 ------------
 137
 138 ### Important note for upgrades from TYPO3 CMS versions **below 6.2 LTS**
 139
 140 It is not possible to upgrade any version below 6.2 LTS to 7 directly,
 141 since some upgrade wizards are not available anymore on 7.
 142
 143 It is highly recommended to upgrade to 6.2 LTS first and continue with
 144 a second upgrade to 7.
 145
 146 ### If SSH and symlinks are possible
 147
 148 If you have SSH access to your webserver and are able to create symlinks,
 149 this is the recommended way of setting up TYPO3 so that it can easily
 150 be upgraded later through the Install Tool:
 151
 152 * Uncompress the `typo3_src-7.6.x.tar.gz` file one level above the Document
 153   Root of your Web server:
 154 ```
 155 /var/www/site/htdocs/ $ cd ..
 156 /var/www/site/ $ tar xzf typo3_src-7.6.x.tar.gz
 157 ```
 158
 159 * Important: If you use GIT to fetch the sources, don't forget to run `composer install --no-dev`
 160   inside the repository, otherwise your installation won't work!
 161
 162 * Create the symlinks in your Document Root:
 163 ```
 164   cd htdocs
 165   ln -s ../typo3_src-7.6.x typo3_src
 166   ln -s typo3_src/index.php
 167   ln -s typo3_src/typo3
 168 ```
 169
 170 * In case you use Apache, copy the .htaccess to your Document Root:
 171 ```
 172   cp typo3_src/_.htaccess .htaccess
 173 ```
 174
 175 You end up with the follow structure of files:
 176
 177 ```
 178   typo3_src-7.6.x/
 179   htdocs/typo3_src -> ../typo3_src-7.6.x/
 180   htdocs/typo3 -> typo3_src/typo3/
 181   htdocs/index.php -> typo3_src/index.php
 182   htdocs/.htaccess
 183 ```
 184
 185 This allows you to upgrade TYPO3 later by simply replacing the symlink
 186 with a newer version, or by using the integrated "Core Updater" which can
 187 be found in the Install Tool.
 188
 189 ### Windows specifics
 190
 191 On Windows Vista and newer you can create symbolic links using the `mklink` tool:
 192 ```
 193   mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-7.6.x
 194   mklink C:\<dir>\example.com\index.php C:\<dir>\typo3_src-7.6.x\index.php
 195 ```
 196
 197 Windows users might need to copy `index.php` from the source directory to the
 198 web site root directory in case the Windows version does not support links
 199 for files.
 200
 201 TYPO3 Core upgrades through the Install Tool is not supported under
 202 Windows.
 203
 204 ### No SSH and symlinks possible (not recommended)
 205
 206 In case you only have FTP or SFTP access to your hosting environment, you
 207 can still install TYPO3, but you won't easily be able to upgrade your
 208 installation once a new patch-level release is out.
 209
 210 Please note that this is not a recommended setup!
 211
 212 * Uncompress `typo3_src-7.6.x.zip` locally
 213 * Upload all files and subdirectories directly in your Document Root
 214   (where files that are served by your webserver are located).
 215 * In case your provider uses Apache, rename the file `_.htaccess` to `.htaccess`.
 216
 217 You end up with this files in your Document Root:
 218
 219 ```
 220  .htaccess
 221  ChangeLog
 222  GPL.txt
 223  index.php
 224  INSTALL.md
 225  LICENSE.txt
 226  NEWS.txt
 227  README.md
 228  typo3/
 229 ```
 230
 231 Installation: further steps
 232 ---------------------------
 233
 234 Now access the web server using a web browser. You will be redirected to the
 235 Install Tool which will walk you through the steps for setting up TYPO3 for
 236 the first time.
 237
 238 It will check if your environment conforms to the minimum system requirements
 239 and gives you some suggestions on what to change in case there are any
 240 discrepancies.
 241
 242 The Install Tool will create the required directory structure for you
 243 (typo3conf, uploads, fileadmin, typo3temp).
 244
 245 Former versions of TYPO3 required the download of a "Dummy Package"
 246 (or "Blank Package"). This is no longer required since version 6.2!
 247
 248 TYPO3 Security
 249 --------------
 250
 251 To ensure a secure installation, you have to make sure that you keep your
 252 TYPO3 core and the extensions up to date.
 253
 254 * Subscribe to the announcement mailing list. This will inform you about new
 255   releases of the TYPO3 core and security bulletins of core and community
 256   extensions.
 257   http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-announce
 258
 259 * Use the scheduler task "Update Extension List (em)" to update the list of
 260   available extensions regularly. You should check regularly, if new versions
 261   of these extensions are available and apply these updates.
 262
 263 * Please refer to official TYPO3 Security Guide for further information
 264   about security-related topics of TYPO3 CMS and the resources compiled by
 265   the Security Team.
 266   https://docs.typo3.org/typo3cms/SecurityGuide/
 267   https://typo3.org/teams/security/resources/
 268
 269 Installation FAQ
 270 ----------------
 271
 272 ### 1
 273 Q:  Why do I get "500 Server error" when I navigate to my TYPO3 web site
 274     immediately after installation?
 275
 276 A:  If you are using Apache web server, check the Apache error log for specifics
 277     on the error. The cause might be some missing module, or some syntax error
 278     in your .htaccess file. The error log is usually located in /var/log/apache2
 279     or /var/log/httpd. Check with your hosting provider if you are in doubt
 280     where the logs are located.
 281
 282 ### 2
 283 Q:  I went through the setup process and created an admin user. Why can't I log
 284     in now?
 285
 286 A:  If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
 287     TYPO3 Install Tool under http://example.com/typo3/install/ (where
 288     example.com is the web site domain), navigate to "All configuration".
 289     Find "setDBinit", and add this line to the top of the input field:
 290 ```
 291         SET SESSION sql_mode=''
 292 ```
 293
 294 ### 3
 295 Q:  Some modules or extensions make Apache crash on Windows. What is the cause?
 296
 297 A:  Fluid uses complex regular expressions which require a lot of stack space
 298     during the first processing. On Windows the default stack size for Apache
 299     is a lot smaller than on unix. You can increase the size to 8MB (default on
 300     unix) by adding to the httpd.conf:
 301 ```
 302         <IfModule mpm_winnt_module>
 303                 ThreadStackSize 8388608
 304         </IfModule>
 305 ```
 306     Restart Apache after this change.