[TASK] Use arrays in str_replace() calls
[Packages/TYPO3.CMS.git] / INSTALL.md
1 INSTALLING TYPO3
2 ================
3
4 TYPO3 is an open source PHP based web content management system released
5 under the GNU GPL. TYPO3 is copyright (c) 1999-2013 by Kasper Skaarhoj.
6
7 This document describes:
8
9 * System requirements for TYPO3
10 * Installation routine
11 * Upgrade routine
12
13 Client browser support
14 ----------------------
15
16 The TYPO3 backend is accessed through a web browser. TYPO3 CMS 6.2 LTS
17 supports the following web browsers:
18
19 * Internet Explorer 8 and later
20 * Google Chrome (Windows, MacOS, Linux)
21 * Firefox (Windows, MacOS, Linux)
22 * Safari on MacOS
23 * and other compatible modern browsers
24
25 Server system requirements
26 --------------------------
27
28 TYPO3 requires a web server with a PHP environment and a database. The minimum
29 system requirements for running TYPO3 CMS 6.2 LTS are:
30
31 * Webserver capable of running PHP applications (Apache, Nginx, IIS or other)
32 * PHP >5.3.7 up to 5.5 (PHP 5.4 or later recommended)
33 * MySQL 5.1 up to 5.6 or compatible
34 * more than 200 MB of disk space
35
36 ### PHP environment
37
38 * memory_limit set to at least 64M
39 * max_execution_time set to at least 30s (240s recommended)
40 * register_globals disabled
41 * disabled safe_mode (not supported)
42 * disabled magic_quotes (not supported)
43 * AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
44   (see FAQ below)
45
46 ### PHP required extensions
47
48 Your PHP needs to support the following extensions. Install will
49 check if these are available.
50
51 * These are usually part of the standard PHP package on most distributions:
52   * fileinfo
53   * filter
54   * hash
55   * openssl
56   * pcre
57   * session
58   * soap
59   * SPL
60   * standard
61   * xml
62   * zip
63   * zlib
64
65 * These might have to be installed separately:
66   * gd
67   * json
68   * mysqli
69
70 ### Recommended setup
71
72 There are plenty of possible setups for high performance TYPO3 installations
73 (i.e. using Varnish Cache, Nginx, PHP-FPM, etc). Consider this resource for
74 more ideas or suggestions:  http://wiki.typo3.org/Performance_tuning
75
76 This is a basic recommended setup for best performance and increased
77 functionality:
78
79 * Apache with mod_expires and mod_rewrite enabled
80
81 * MySQL 5.1 or newer
82
83 * GraphicsMagick or ImageMagick v6 or newer installed on the server
84
85 * PHP
86   * version 5.4 or later
87   * memory_limit set to at least 128M
88   * max_execution_time set to at least 240s
89
90 * Additional PHP extensions:
91   * PHP opcode cache, i.e.: apc, xcache, eaccelerator, Zend Optimizer,
92     Zend OPcache, wincache (in case of an IIS installation)
93   * apc caching (with at least 100 MB of memory available)
94   * curl
95   * mbstring
96   * FreeType (usually included within the PHP distribution)
97
98 * PHP access to /dev/urandom or /dev/random on Unix-like platforms for
99   increased security. Make sure to add "/dev/random:/dev/urandom" to
100   open_basedir settings if you use it. If these paths are unavailable, TYPO3
101   will attempt to simulate random number generation. This is less secure,
102   reduces performance and throws out warnings in the TYPO3 system log.
103
104 * TYPO3 works with PHP's IPv6 support, which is enabled by default since
105   PHP 5.3. If you compile PHP 5.3 on your own, be aware not to use option
106   "--disable-ipv6", because this will break the IPv6 support and the according
107   unit tests.
108
109 Installation
110 ------------
111
112 ### If SSH and symlinks are possible
113
114 If you have SSH access to your webserver and are able to create symlinks,
115 this is the recommended way of setting up TYPO3 so that it can easily
116 be upgraded later through the Install Tool:
117
118 * Uncompress the `typo3_src-6.2.x.tar.gz` file one level above the Document
119   Root of your Web server:
120 ```
121 /var/www/site/htdocs/ $ cd ..
122 /var/www/site/ $ tar xzf typo3_src-6.2.x.tar.gz
123 ```
124
125 * Create the symlinks in your Document Root:
126 ```
127   cd htdocs
128   ln -s ../typo3_src-6.2.x typo3_src
129   ln -s typo3_src/index.php index.php
130   ln -s typo3_src/typo3 typo3
131 ```
132
133 * In case you use Apache, copy the .htaccess to your Document Root:
134 ```
135   cp typo3_src/_.htaccess .htaccess
136 ```
137
138 You end up with the follow structure of files:
139
140 ```
141   typo3_src-6.2.x/
142   htdocs/typo3_src -> ../typo3_src-6.2.x/
143   htdocs/typo3 -> typo3_src/typo3/
144   htdocs/index.php -> typo3_src/index.php
145   htdocs/.htaccess
146 ```
147
148 This allows you to upgrade TYPO3 later by simply replacing the symlink
149 with a newer version, or by using the integrated "Core Updater" which can
150 be found in the Install Tool.
151
152 ### Windows specifics
153
154 On Windows Vista and Windows 7, you can create symbolic links using
155 the `mklink` tool:
156 ```
157   mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-6.2.x
158 ```
159
160 Users of Windows XP/2000 or newer can use the `junction` program by
161 Marc Russinovich to create links. It can be downloaded at
162 http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
163
164 Windows users might need to copy `index.php` from the source directory to the
165 web site root directory in case the Windows version does not support links
166 for files.
167
168 TYPO3 Core upgrades through the Install Tool is not supported under
169 Windows.
170
171 ### No SSH and symlinks possible (not recommended)
172
173 In case you only have FTP or SFTP access to your hosting environment, you
174 can still install TYPO3, but you won't easily be able to upgrade your
175 installation once a new patchlevel release is out.
176
177 Please note that this is not a recommended setup!
178
179 * Uncompress `typo3_src-6.2.x.tar.gz` locally
180 * Upload all files and subdirectories directly in your Document Root
181   (where files that are served by your webserver are located).
182 * In case your provider uses Apache:
183   * rename `_.htaccess` to `.htaccess`
184
185 You end up with this files in your Document Root:
186
187 ```
188  .htaccess
189  ChangeLog
190  GPL.txt
191  index.php
192  INSTALL.md
193  LICENSE.txt
194  NEWS.txt
195  README.md
196  typo3/
197 ```
198
199 Installation: further steps
200 ---------------------------
201
202 Now access the web server using a web browser. You will be redirected to the
203 Install Tool which will walk you through the steps for setting up TYPO3 for
204 the first time.
205
206 It will check if your environment conforms to the minimum system requirements
207 and gives you some suggestions on what to change in case there are any
208 discrepancies.
209
210 The Install Tool will create the required directory structure for you
211 (typo3conf, uploads, fileadmin, typo3temp).
212
213 Former versions of TYPO3 required the download of a "Dummy Package"
214 (or "Blank Package"). This is no longer required since version 6.2!
215
216 TYPO3 Security
217 --------------
218
219 To ensure a secure installation, you have to make sure that you keep your
220 TYPO3 core and the extensions up to date.
221
222 * Subscribe to the announcement mailing list. This will inform you about new
223   releases of the TYPO3 core and security bulletins of core and community
224   extensions.
225   http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-announce
226
227 * Use the scheduler task "Update Extension List (em)" to update the list of
228   available extensions regularly. You should check regularly, if new versions
229   of these extensions are available and apply these updates.
230
231 * Please refer to official TYPO3 Security Guide for further information
232   about security-related topics of TYPO3 CMS and the resources compiled by
233   the Security Team.
234   http://docs.typo3.org/typo3cms/SecurityGuide/
235   http://typo3.org/teams/security/resources/
236
237 Installation FAQ
238 ----------------
239
240 ### 1
241 Q:  Why do I get "500 Server error" when I navigate to my TYPO3 web site
242     immediately after installation?
243
244 A:  If you are using Apache web server, check the Apache error log for specifics
245     on the error. The cause might be some missing module, or some syntax error
246     in your .htaccess file. The error log is usually located in /var/log/apache2
247     or /var/log/httpd. Check with your hosting provider if you are in doubt
248     where the logs are located.
249
250 ### 2
251 Q:  I went through the setup process and created an admin user. Why can't I log
252     in now?
253
254 A:  If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
255     TYPO3 Install Tool under http://example.com/typo3/install/ (where
256     example.com is the web site domain), navigate to "All configuration".
257     Find "setDBinit", and add this line to the top of the input field:
258 ```
259         SET SESSION sql_mode='MYSQL40'
260 ```
261
262 ### 3
263 Q:  Some modules or extensions make Apache crash on Windows. What is the cause?
264
265 A:  Fluid uses complex regular expressions which require a lot of stack space
266     during the first processing. On Windows the default stack size for Apache
267     is a lot smaller than on unix. You can increase the size to 8MB (default on
268     unix) by adding to the httpd.conf:
269 ```
270         <IfModule mpm_winnt_module>
271                 ThreadStackSize 8388608
272         </IfModule>
273 ```
274     Restart Apache after this change.