INSTALL.txt

   1 *******************************************************************************
   2 INSTALLING TYPO3
   3 $Id$
   4 *******************************************************************************
   5
   6 This document is a part of the TYPO3 project. TYPO3 is an open source web
   7 content management system released under the GNU GPL. TYPO3 is copyright
   8 (c) 1999-2009 by Kasper Skaarhoj.
   9
  10 This document describes the system requirements for TYPO3 and the installation
  11 routine.
  12
  13
  14 ===============================================================================
  15 System requirements
  16 ===============================================================================
  17
  18 TYPO3 requires a web server with a PHP installation and a database. While TYPO3
  19 can be configured to run on many web servers with different databases, this
  20 document assumes that Apache and MySQL will be used. This document does not
  21 cover using TYPO3 with other databases or web servers.
  22
  23 The following configuration is the minimum required:
  24 - a web server capable of running PHP
  25 - PHP 5.2.0 or newer with the following extensions:
  26         - filter
  27         - GD2
  28         - JSON
  29         - mysql
  30         - pcre
  31         - session
  32         - SPL
  33         - standard
  34         - xml
  35         - zlib
  36         Some extensions can be optionally compiled into PHP. A list of loaded
  37         extensions can be checked using the phpinfo() function.
  38 - memory_limit set to at least to 64M in php.ini
  39 - MySQL 4.1 or newer
  40 - 200 MB of disk space
  41 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
  42   (see FAQ below)
  43
  44 The following configuration is recommended:
  45 - Apache 2.x
  46 - mod_expires and mod_rewrite enabled in the Apache configuration
  47 - PHP 5.2.0 or newer with the following extensions:
  48         - cURL
  49         - filter
  50         - GD2
  51         - hash
  52         - JSON
  53         - mbstring
  54         - mysql
  55         - pcre
  56         - session
  57         - SPL
  58         - standard
  59         - xml
  60         - zlib
  61         Some extensions can be optionally compiled into PHP. A list of loaded
  62         extensions can be checked using the phpinfo() function.
  63 - memory_limit set to 128M or more in php.ini
  64 - MySQL 5.1 or newer
  65 - GraphicsMagick
  66 - 200 MB or more of disk space
  67 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
  68   (see FAQ below)
  69
  70 TYPO3 uses /dev/urandom or /dev/random on Unix-like platforms for security
  71 purposes. Access to these files is highly recommended and increases TYPO3
  72 security. Make sure to add "/dev/random:/dev/urandom" to open_basedir
  73 settings if you use it. If these paths are unavailable, TYPO3 will attempt to
  74 simulate random number generation. This is less secure, causes performance
  75 issues and warnings in the TYPO3 system log.
  76
  77 ===============================================================================
  78 Obtaining TYPO3
  79 ===============================================================================
  80
  81 To get TYPO3, navigate to the following location:
  82         http://typo3.org/download/packages/
  83
  84 TYPO3 consists of two packages: source and dummy. The source package contains
  85 files that are the same for every TYPO3 web site. The dummy package contains
  86 files unique to each TYPO3 installation.
  87
  88 To install TYPO3, both packages must be downloaded.
  89
  90
  91 ===============================================================================
  92 Installation: simple (not recommended!)
  93 ===============================================================================
  94
  95 This procedure is not recommended because it makes upgrades harder. However, it
  96 can be the only option if you hosting company does not provide SSH access to
  97 the web server.
  98
  99 To install TYPO3, unpack the source package locally. Unpacking will produce a
 100 directory with a name like typo3_src-x.y.z, where x, y and z correspond to the
 101 TYPO3 version. For example, the TYPO3 4.3.0 source package will create a
 102 directory named typo3_src-4.3.0.
 103
 104 Next unpack the dummy package. This will create a directory with the name
 105 dummy-x.y.z. Now create a new directory and copy all files and folders from
 106 within typo3_src-x.y.z and dummy-x.y.z into this new directory.
 107
 108 Use a FTP or SFTP program or any other available way to upload all files to
 109 the web server.
 110
 111 Change permissions of the directories and files. The following directories and
 112 files should be read-only for the web server:
 113         t3lib/
 114         typo3/
 115         index.php
 116
 117 All other directories should be writable for the web server. If in doubt,
 118 contact your hosting company and ask them to assist in adjusting permissions.
 119
 120
 121 ===============================================================================
 122 Installation: recommended
 123 ===============================================================================
 124
 125 To install TYPO3, unpack the source package outside of the web site root
 126 directory on your server. The location must be accessible to the web server.
 127 Unpacking will produce a directory with a name like typo3_src-x.y.z, where x,
 128 y and z correspond to the TYPO3 version. For example, the TYPO3 4.3.0 source
 129 package will create a directory named typo3_src-4.3.0.
 130
 131 Unpack the dummy package in the temporary location on the server. This will
 132 create a dummy-x.y.z directory. Move all files and directories from the
 133 dummy-x.y.z directory to the web site root directory.
 134
 135 Linux, Unix and Mac OS X users should use the tar.gz packages and unpack them
 136 using:
 137         tar xzf source-x.y.z
 138         tar xzf dummy-x.y.z
 139
 140 Windows users can use Windows built-in unpacker on unpack ZIP versions of
 141 packages.
 142
 143 On Linux, Unix or Mac OS X systems create a symbolic link named typo3_src
 144 pointing to the source package:
 145         ln -s /var/www/typo3_src-4.3.0 /var/www/example.com/typo3_src
 146
 147 On Windows Vista or Windows 7 create a symbolic link named typo3_src
 148 pointing to the source package:
 149         mklink /D C:\<dir>\typo3_src-4.3.0 C:\<dir>\example.com\typo3_src
 150
 151 Users of Windows XP/2000 can use the "junction" program by Marc Russinovich to
 152 create links. The program can be obtained at:
 153         http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
 154
 155 Next create links for the typo3/ and t3lib/ directories:
 156 cd /var/www/example.com
 157         ln -s typo3_src/t3lib
 158         ln -s typo3_src/typo3
 159
 160 Linux, Unix and Mac OS X users also create a symbolic link to index.php
 161         ln -s typo3_src/index.php
 162
 163 Windows users must copy index.php from the source directory to the web site
 164 root directory because Windows does not support links for files.
 165
 166 Change permissions and ownership of the directories. This usually requires the
 167 "sudo" command. Assuming that the web server user is in the group named
 168 "apache", execute the following commands in the web site root directory:
 169         sudo chgrp -R apache fileadmin typo3temp typo3conf uploads
 170         sudo chmod -R g+rwX,o-w fileadmin typo3temp typo3conf uploads
 171
 172 If "sudo" is not available, ask your hosting company to change the permissions.
 173
 174
 175 ===============================================================================
 176 Setting up TYPO3
 177 ===============================================================================
 178
 179 To set up TYPO3, navigate to your web site. The TYPO3 installer will run in the
 180 1-2-3 mode to easily guide you through the installation.
 181
 182
 183 ===============================================================================
 184 Troubleshooting
 185 ===============================================================================
 186
 187 For troubleshooting read the FAQ below. If your problem is not listed, feel
 188 free to ask questions in the TYPO3 mailing lists:
 189         http://typo3.org/community/mailing-lists/
 190
 191
 192 ===============================================================================
 193 FAQ
 194 ===============================================================================
 195
 196 Q:      Why do I get "500 Server error" when I navigate to my TYPO3 web site
 197         immediately after installation?
 198 A:      Make sure that AllowOverride allows "Indexes" and "FileInfo" in the Apache
 199         configuration. If you cannot ensure this, rename .htaccess files to
 200         _.htaccess. TYPO3 will run but considerably slower.
 201         Here is the list of the files to rename:
 202                 typo3/contrib/.htaccess
 203                 typo3/gfx/.htaccess
 204                 typo3/mod/user/ws/.htaccess
 205                 typo3/sysext/.htaccess
 206                 typo3/sysext/t3skin/stylesheets/.htaccess
 207         If the error does not disappear, web server error logs should help. For
 208         Apache, the error log is usually located in /var/log/apache2 or
 209         /var/log/httpd. Check with your hosting provider if you are in doubt where
 210         the logs are located.
 211
 212 Q:      Backend or Installer looks strange, no images just black and white?
 213 A:      Maybe you missed some configuration in your .htaccess file.
 214         Have a look at typo3_src/misc/advanced.htaccess to find the options
 215         you might need.
 216
 217 Q:      I went through the setup process and created an admin user. Why can't I log
 218         in now?
 219 A:      If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
 220         TYPO3 Install tool under http://example.com/typo3/install/ (where example.com
 221         is the web site domain), navigate to "All configuration". find "setDBinit",
 222         and add this line to the top of the input field:
 223                 SET SESSION sql_mode='MYSQL40'