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