INSTALL.txt

   1 *******************************************************************************
   2 INSTALLING TYPO3
   3 *******************************************************************************
   4
   5 This document is a part of the TYPO3 project. TYPO3 is an open source web
   6 content management system released under the GNU GPL. TYPO3 is copyright
   7 (c) 1999-2013 by Kasper Skaarhoj.
   8
   9 This document describes the system requirements for TYPO3 and the installation
  10 routine.
  11
  12
  13 ===============================================================================
  14 System requirements
  15 ===============================================================================
  16
  17 TYPO3 requires a web server with a PHP installation and a database. While TYPO3
  18 can be configured to run on many web servers with different databases, this
  19 document assumes that Apache and MySQL will be used. This document does not
  20 cover using TYPO3 with other databases or web servers.
  21
  22 The following configuration is the minimum required:
  23
  24 - a web server capable of running PHP
  25 - PHP 5.3.0 or newer with the following extensions:
  26         - fileinfo
  27         - filter
  28         - GD2
  29         - JSON
  30         - mysqli
  31         - openssl
  32         - pcre
  33         - session
  34         - SOAP
  35         - SPL
  36         - standard
  37         - xml
  38         - zlib
  39 - memory_limit set to at least 64M in php.ini
  40 - register_globals is disabled in php.ini
  41 - MySQL 5.0 or newer
  42 - 200 MB of disk space
  43 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
  44   (see FAQ below)
  45 - Apache stack size 8MB (or more). (see FAQ below)
  46
  47 The following configuration is recommended:
  48
  49 - Apache 2.x
  50 - mod_expires and mod_rewrite enabled in the Apache configuration
  51 - PHP 5.3.7 or newer with the following extensions:
  52         - cURL
  53         - fileinfo
  54         - filter
  55         - GD2
  56         - hash
  57         - JSON
  58         - mbstring
  59         - mysqli
  60         - openssl
  61         - pcre
  62         - session
  63         - SOAP
  64         - SPL
  65         - standard
  66         - xml
  67         - zlib
  68 - Safe mode is not supported, thus it must not be activated
  69 - Magic Quotes is deprecated, thus it should be deactivated
  70 - memory_limit set to 128M or more in php.ini
  71 - MySQL 5.1 or newer
  72 - FreeType 2
  73 - GraphicsMagick or ImageMagick v6 or newer
  74 - 200 MB or more of disk space
  75 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
  76   (see FAQ below)
  77
  78 Since PHP below version 5.3.7 has a bug in correctly resolving type hints being
  79 in method signatures of interfaces - which need to be defined using a map for
  80 class aliases - we suggest to use at least PHP 5.3.7. Find more details here:
  81 - https://bugs.php.net/bug.php?id=54624
  82 - http://forge.typo3.org/issues/40653
  83
  84 TYPO3 uses /dev/urandom or /dev/random on Unix-like platforms for security
  85 purposes. Access to these files is highly recommended and increases TYPO3
  86 security. Make sure to add "/dev/random:/dev/urandom" to open_basedir
  87 settings if you use it. If these paths are unavailable, TYPO3 will attempt to
  88 simulate random number generation. This is less secure, causes performance
  89 issues and warnings in the TYPO3 system log.
  90
  91 TYPO3 relies on IPv6 support, which is by default enabled since PHP 5.3.
  92 Take care not to compile PHP 5.3 with the option "--disable-ipv6", because
  93 this will break the IPv6 support and the according unit tests.
  94
  95 ===============================================================================
  96 Obtaining TYPO3
  97 ===============================================================================
  98
  99 To get TYPO3, navigate to the following location:
 100         http://typo3.org/download/
 101
 102 TYPO3 consists of two packages: source and dummy. The source package contains
 103 files that are the same for every TYPO3 web site. The dummy package contains
 104 files unique to each TYPO3 installation.
 105
 106 To install TYPO3, both packages must be downloaded.
 107
 108
 109 ===============================================================================
 110 Installation: simple (not recommended!)
 111 ===============================================================================
 112
 113 This procedure is not recommended because it makes upgrades harder. However, it
 114 can be the only option if you hosting company does not provide SSH access to
 115 the web server.
 116
 117 To install TYPO3, unpack the source package locally. Unpacking will produce a
 118 directory with a name like typo3_src-x.y.z, where x, y and z correspond to the
 119 TYPO3 version. For example, the TYPO3 x.y.z source package will create a
 120 directory named typo3_src-x.y.z.
 121
 122 Next unpack the dummy package. This will create a directory with the name
 123 dummy-x.y.z. Now create a new directory and copy all files and folders from
 124 within typo3_src-x.y.z and dummy-x.y.z into this new directory.
 125
 126 Use a FTP or SFTP program or any other available way to upload all files to
 127 the web server.
 128
 129 Change permissions of the directories and files. The following directories and
 130 files should be read-only for the web server:
 131         typo3/
 132         index.php
 133
 134 All other directories should be writable for the web server. If in doubt,
 135 contact your hosting company and ask them to assist in adjusting permissions.
 136
 137
 138 ===============================================================================
 139 Installation: recommended
 140 ===============================================================================
 141
 142 To install TYPO3, unpack the source package outside of the web site root
 143 directory on your server. The location must be accessible to the web server.
 144 Unpacking will produce a directory with a name like typo3_src-x.y.z, where x,
 145 y and z correspond to the TYPO3 version. For example, the TYPO3 4.6.0 source
 146 package will create a directory named typo3_src-4.6.0.
 147
 148 Unpack the dummy package in the temporary location on the server. This will
 149 create a dummy-x.y.z directory. Move all files and directories from the
 150 dummy-x.y.z directory to the web site root directory.
 151
 152 Linux, Unix and Mac OS X users should use the tar.gz packages and unpack them
 153 using:
 154         tar xzf source-x.y.z
 155         tar xzf dummy-x.y.z
 156
 157 Windows users can use Windows built-in unpacker on unpack ZIP versions of
 158 packages.
 159
 160 On Linux, Unix or Mac OS X systems create a symbolic link named typo3_src
 161 pointing to the source package:
 162         ln -s /var/www/typo3_src-4.6.0 /var/www/example.com/typo3_src
 163
 164 On Windows Vista or Windows 7 create a symbolic link named typo3_src
 165 pointing to the source package:
 166         mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-4.6.0
 167
 168 Users of Windows XP/2000 or newer can use the "junction" program by
 169 Marc Russinovich to create links. The program can be obtained at:
 170         http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
 171
 172 Next create link for the typo3/ directory:
 173 cd /var/www/example.com
 174         ln -s typo3_src/typo3
 175
 176 Linux, Unix and Mac OS X users also create a symbolic link to index.php
 177         ln -s typo3_src/index.php
 178
 179 Windows users must copy index.php from the source directory to the web site
 180 root directory because Windows does not support links for files.
 181
 182 Change permissions and ownership of the directories. This usually requires the
 183 "sudo" command. Assuming that the web server user is in the group named
 184 "apache", execute the following commands in the web site root directory:
 185         sudo chgrp -R apache fileadmin typo3temp typo3conf uploads
 186         sudo chmod -R g+rwX,o-w fileadmin typo3temp typo3conf uploads
 187
 188 If "sudo" is not available, ask your hosting company to change the permissions.
 189
 190
 191 ===============================================================================
 192 Setting up TYPO3
 193 ===============================================================================
 194
 195 To set up TYPO3, navigate to your web site. The TYPO3 installer will run in the
 196 1-2-3 mode to easily guide you through the installation.
 197
 198
 199 ===============================================================================
 200 Troubleshooting
 201 ===============================================================================
 202
 203 For troubleshooting read the FAQ below. If your problem is not listed, feel
 204 free to ask questions in the TYPO3 mailing lists:
 205         http://typo3.org/support/mailing-lists/
 206
 207
 208 ===============================================================================
 209 FAQ
 210 ===============================================================================
 211
 212 Q:      Why do I get "500 Server error" when I navigate to my TYPO3 web site
 213         immediately after installation?
 214 A:      Make sure that AllowOverride allows "Indexes" and "FileInfo" in the Apache
 215         configuration. If you cannot ensure this, rename .htaccess files to
 216         _.htaccess. TYPO3 will run but considerably slower.
 217         Here is the list of the files to rename:
 218                 typo3/contrib/.htaccess
 219                 typo3/gfx/.htaccess
 220                 typo3/mod/user/ws/.htaccess
 221                 typo3/sysext/.htaccess
 222                 typo3/sysext/t3skin/stylesheets/.htaccess
 223         If the error does not disappear, web server error logs should help. For
 224         Apache, the error log is usually located in /var/log/apache2 or
 225         /var/log/httpd. Check with your hosting provider if you are in doubt where
 226         the logs are located.
 227
 228 Q:      Backend or Installer looks strange, no images just black and white?
 229 A:      Maybe you missed some configuration in your .htaccess file.
 230         Have a look at typo3_src/misc/advanced.htaccess to find the options
 231         you might need.
 232
 233 Q:      I went through the setup process and created an admin user. Why can't I log
 234         in now?
 235 A:      If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
 236         TYPO3 Install tool under http://example.com/typo3/install/ (where example.com
 237         is the web site domain), navigate to "All configuration". find "setDBinit",
 238         and add this line to the top of the input field:
 239                 SET SESSION sql_mode='MYSQL40'
 240
 241 Q:      Some modules or extensions make Apache crash on Windows. What is the cause?
 242 A:      Fluid uses complex regular expressions which require a lot of stack space
 243         during the first processing. On Windows the default stack size for Apache
 244         is a lot smaller than on unix. You can increase the size to 8MB (default on
 245         unix) by adding to the httpd.conf:
 246                 <IfModule mpm_winnt_module>
 247                         ThreadStackSize 8388608
 248                 </IfModule>
 249         Restart Apache after this change.
 250
 251 Q:      What do I have to do regarding security?
 252 A:      You have to make sure that you keep your TYPO3-core and the extensions
 253         up to date.
 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         * Use the scheduler task "Update Extension List (em)" to update the list of
 259           available extensions regularly. You should check regularly, if new versions
 260           of these extensions are available and install them respectively.
 261         * For further reading regarding securing TYPO3, please read the TYPO3 security
 262           cookbook and other resources. Please visit
 263           http://typo3.org/teams/security/resources/