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