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