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