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