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