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