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