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