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