[TASK] Switch from git.typo3.org to github for testing
[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-2018 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 v9
17 supports the following web browsers:
18
19 * Internet Explorer 11 and later
20 * Microsoft Edge
21 * Google Chrome (Windows, MacOS X, Linux)
22 * Firefox (Windows, MacOS X, Linux)
23 * Safari on MacOS X
24 * and other compatible modern browsers
25
26 Server system requirements
27 --------------------------
28
29 TYPO3 requires a web server with a PHP environment and a database. The minimum
30 system requirements for running TYPO3 v9 are:
31
32 * Webserver capable of running PHP applications (Apache, Nginx, IIS or other)
33 * PHP 7.2
34 * MySQL 5.5 up to 5.7 or compatible
35 * more than 200 MB of disk space
36
37 Note: If you use any other webserver than Apache, make sure you add the necessary configuration normally
38 provided in the various `.htaccess` files inside the TYPO3 core. This configuration is security relevant,
39 therefore only experienced server administrators should create such configuration.
40
41 ### MySQL environment
42
43 TYPO3 works with MySQL in the above mentioned versions. It will also work on
44 compatible "drop-in" replacements like MariaDB or Percona. The InnoDB engine
45 is required to be enabled.
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 30 (240 seconds recommended)
63 * AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
64   (see FAQ below)
65
66 ### PHP required extensions
67
68 Your PHP needs to support the following extensions. Install will
69 check if these are available.
70
71 * These are usually part of the standard PHP package on most distributions:
72   * filter
73   * hash
74   * openssl
75   * pcre >= 8.38
76   * session
77   * SPL
78   * standard
79   * xml
80   * zip
81   * zlib
82
83 * These might have to be installed separately:
84   * gd
85   * intl
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 7.2 or later
106   * memory_limit set to at least 128M
107   * max_execution_time set to at least 240
108   * max_input_vars set to at least 1500
109
110 * Additional PHP extensions:
111   * PHP opcode cache, i.e.: apc, xcache, eaccelerator, Zend Optimizer, wincache (in case of an IIS installation)
112   * apcu caching (with at least 100 MB of memory available)
113   * curl
114   * mbstring
115   * FreeType 2 (usually included within the PHP distribution)
116   * bcmath or gmp (needed if you'd like to use the openid system extension)
117   * fileinfo (mandatory for proper file type detection)
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 7 LTS**
133
134 It is not possible to upgrade any version below 7 LTS to 8 directly,
135 since some upgrade wizards are not available anymore on 8 and 9.
136
137 It is highly recommended to upgrade to 7 LTS first and continue with
138 a second upgrade to 8 and then upgrade to 9.
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-9.x.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-9.x.x.tar.gz
151 ```
152
153 * Important: If you use GIT to fetch the sources, don't forget to run the following commands,
154 otherwise your installation won't work!
155 ```
156 cd typo3_src
157 composer install --no-dev
158 cd ..
159 ```
160
161 * Create the symlinks in your Document Root:
162 ```
163   cd htdocs
164   ln -s ../typo3_src-9.x.x typo3_src
165   ln -s typo3_src/index.php
166   ln -s typo3_src/typo3
167 ```
168
169 * In case you use Apache, copy the .htaccess to your Document Root:
170 ```
171   cp typo3_src/_.htaccess .htaccess
172 ```
173
174 * In case you use IIS, install the URL Rewrite 2.x module and copy the web.config to your Document Root:
175 ```
176   cp typo3_src/_web.config web.config
177 ```
178
179 You end up with the follow structure of files:
180
181 ```
182   typo3_src-9.x.x/
183   htdocs/typo3_src -> ../typo3_src-9.x.x/
184   htdocs/typo3 -> typo3_src/typo3/
185   htdocs/index.php -> typo3_src/index.php
186   htdocs/.htaccess (only on Apache)
187   htdocs/web.config (only on IIS)
188 ```
189
190 This allows you to upgrade TYPO3 later by simply replacing the symlink
191 with a newer version, or by using the integrated "Core Updater" which can
192 be found in the Install Tool.
193
194 ### Windows specifics
195
196 #### Symlinks
197
198 On Windows Vista and newer you can create symbolic links using the `mklink` tool:
199 ```
200   mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-9.x.x
201   mklink C:\<dir>\example.com\index.php C:\<dir>\typo3_src-9.x.x\index.php
202 ```
203 Be aware that administrator rights might be needed in order to create the symlinks.
204
205 Windows users might need to copy `index.php` from the source directory to the
206 web site root directory in case the Windows version does not support links
207 for files.
208
209 TYPO3 Core upgrades through the Install Tool is not supported under
210 Windows.
211
212 #### Path length
213
214 Up until PHP 7.0 Windows has had problems with lengths of a path.
215 The TYPO3 core enforces a maximum path length of 160 characters in itself, leaving
216 100 characters for your installation directory. Please note that these 100 characters
217 are counted including the drive identifier (C:\ for example).
218
219 In case you use composer to install your TYPO3 instance, be aware that composer will
220 try to unpack TYPO3 into composer's cache dir first and then move the files to your
221 target directory.
222 Because composer's cache dir defaults to C:\Users\<user>\AppData\Local\Composer it is
223 possible your full path becomes more than the 100 characters you're allowed to use.
224
225 You can use the `cache-dir` directive to set a shorter directory specifically for
226 your TYPO3 instance.
227
228 See: https://getcomposer.org/doc/06-config.md#cache-dir
229
230 ### No SSH and symlinks possible (not recommended)
231
232 In case you only have FTP or SFTP access to your hosting environment, you
233 can still install TYPO3, but you won't easily be able to upgrade your
234 installation once a new patch-level release is out.
235
236 Please note that this is not a recommended setup!
237
238 * Uncompress `typo3_src-9.x.x.zip` locally
239 * Upload all files and subdirectories directly in your Document Root
240   (where files that are served by your webserver are located).
241 * In case your provider uses Apache, rename the file `_.htaccess` to `.htaccess`.
242 * In case your provider uses IIS, rename the file `_web.config` to `web.config`.
243
244 You end up with this files in your Document Root:
245
246 ```
247  .htaccess (only on Apache)
248  web.config (only on IIS)
249  CONTRIBUTING.md
250  index.php
251  INSTALL.md
252  LICENSE.txt
253  README.md
254  typo3/
255 ```
256
257 Installation: further steps
258 ---------------------------
259
260 Now access the web server using a web browser. You will be redirected to the
261 Install Tool which will walk you through the steps for setting up TYPO3 for
262 the first time.
263
264 It will check if your environment conforms to the minimum system requirements
265 and gives you some suggestions on what to change in case there are any
266 discrepancies.
267
268 The Install Tool will create the required directory structure for you
269 (typo3conf, fileadmin, typo3temp).
270
271 TYPO3 Security
272 --------------
273
274 To ensure a secure installation, you have to make sure that you keep your
275 TYPO3 core and the extensions up to date.
276
277 * Subscribe to the announcement mailing list. This will inform you about new
278   releases of the TYPO3 core and security bulletins of core and community
279   extensions.
280   http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-announce
281
282 * Use the scheduler task "Update Extension List (em)" to update the list of
283   available extensions regularly. You should check regularly, if new versions
284   of these extensions are available and apply these updates.
285
286 * Please refer to official TYPO3 Security Guide for further information
287   about security-related topics of TYPO3 CMS and the resources compiled by
288   the Security Team.
289   https://docs.typo3.org/typo3cms/SecurityGuide/
290   https://typo3.org/teams/security/resources/
291
292 Installation FAQ
293 ----------------
294
295 ### 1
296 Q:  Why do I get "500 Server error" when I navigate to my TYPO3 web site
297     immediately after installation?
298
299 A:  If you are using Apache web server, check the Apache error log for specifics
300     on the error. The cause might be some missing module, or some syntax error
301     in your .htaccess file. The error log is usually located in /var/log/apache2
302     or /var/log/httpd. Check with your hosting provider if you are in doubt
303     where the logs are located.
304
305 ### 2
306 Q:  I went through the setup process and created an admin user. Why can't I log
307     in now?
308
309 A:  If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
310     TYPO3 Install Tool under http://example.com/typo3/install/ (where
311     example.com is the web site domain), navigate to "All configuration".
312     Find "setDBinit", and add this line to the top of the input field:
313 ```
314         SET SESSION sql_mode=''
315 ```
316
317 ### 3
318 Q:  Some modules or extensions make Apache crash on Windows. What is the cause?
319
320 A:  Fluid uses complex regular expressions which require a lot of stack space
321     during the first processing. On Windows the default stack size for Apache
322     is a lot smaller than on unix. You can increase the size to 8MB (default on
323     unix) by adding to the httpd.conf:
324 ```
325         <IfModule mpm_winnt_module>
326                 ThreadStackSize 8388608
327         </IfModule>
328 ```
329     Restart Apache after this change.