[TASK] ext:install Improve wording in empty database select
[Packages/TYPO3.CMS.git] / INSTALL.txt
1 *******************************************************************************
2 INSTALLING TYPO3
3 *******************************************************************************
4
5 This document is a part of the TYPO3 project. TYPO3 is an open source web
6 content management system released under the GNU GPL. TYPO3 is copyright
7 (c) 1999-2013 by Kasper Skaarhoj.
8
9 This document describes the system requirements for TYPO3 and the installation
10 routine.
11
12
13 ===============================================================================
14 System requirements
15 ===============================================================================
16
17 TYPO3 requires a web server with a PHP installation and a database. While TYPO3
18 can be configured to run on many web servers with different databases, this
19 document assumes that Apache and MySQL will be used. This document does not
20 cover using TYPO3 with other databases or web servers.
21
22 The following configuration is the minimum required:
23
24 - a web server capable of running PHP
25 - PHP 5.3.7 or newer with the following extensions:
26         - fileinfo
27         - filter
28         - GD2
29         - JSON
30         - mysqli
31         - openssl
32         - pcre
33         - session
34         - SOAP
35         - SPL
36         - standard
37         - xml
38         - zlib
39 - memory_limit set to at least 64M in php.ini
40 - register_globals is disabled in php.ini
41 - MySQL 5.0 or newer
42 - 200 MB of disk space
43 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
44   (see FAQ below)
45 - Apache stack size 8MB (or more). (see FAQ below)
46
47 The following configuration is recommended:
48
49 - Apache 2.x
50 - mod_expires and mod_rewrite enabled in the Apache configuration
51 - PHP 5.3.7 or newer with the following extensions:
52         - cURL
53         - fileinfo
54         - filter
55         - GD2
56         - hash
57         - JSON
58         - mbstring
59         - mysqli
60         - openssl
61         - pcre
62         - session
63         - SOAP
64         - SPL
65         - standard
66         - xml
67         - zlib
68 - Safe mode is not supported, thus it must not be activated
69 - Magic Quotes is deprecated, thus it should be deactivated
70 - memory_limit set to 128M or more in php.ini
71 - MySQL 5.1 or newer
72 - FreeType 2
73 - GraphicsMagick or ImageMagick v6 or newer
74 - 200 MB or more of disk space
75 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
76   (see FAQ below)
77
78 TYPO3 uses /dev/urandom or /dev/random on Unix-like platforms for security
79 purposes. Access to these files is highly recommended and increases TYPO3
80 security. Make sure to add "/dev/random:/dev/urandom" to open_basedir
81 settings if you use it. If these paths are unavailable, TYPO3 will attempt to
82 simulate random number generation. This is less secure, causes performance
83 issues and warnings in the TYPO3 system log.
84
85 TYPO3 relies on IPv6 support, which is by default enabled since PHP 5.3.
86 Take care not to compile PHP 5.3 with the option "--disable-ipv6", because
87 this will break the IPv6 support and the according unit tests.
88
89 ===============================================================================
90 Obtaining TYPO3
91 ===============================================================================
92
93 To get TYPO3, navigate to the following location:
94         http://typo3.org/download/
95
96 TYPO3 consists of two packages: source and dummy. The source package contains
97 files that are the same for every TYPO3 web site. The dummy package contains
98 files unique to each TYPO3 installation.
99
100 To install TYPO3, both packages must be downloaded.
101
102
103 ===============================================================================
104 Installation: simple (not recommended!)
105 ===============================================================================
106
107 This procedure is not recommended because it makes upgrades harder. However, it
108 can be the only option if you hosting company does not provide SSH access to
109 the web server.
110
111 To install TYPO3, unpack the source package locally. Unpacking will produce a
112 directory with a name like typo3_src-x.y.z, where x, y and z correspond to the
113 TYPO3 version. For example, the TYPO3 x.y.z source package will create a
114 directory named typo3_src-x.y.z.
115
116 Next unpack the dummy package. This will create a directory with the name
117 dummy-x.y.z. Now create a new directory and copy all files and folders from
118 within typo3_src-x.y.z and dummy-x.y.z into this new directory.
119
120 Use a FTP or SFTP program or any other available way to upload all files to
121 the web server.
122
123 Change permissions of the directories and files. The following directories and
124 files should be read-only for the web server:
125         typo3/
126         index.php
127
128 All other directories should be writable for the web server. If in doubt,
129 contact your hosting company and ask them to assist in adjusting permissions.
130
131
132 ===============================================================================
133 Installation: recommended
134 ===============================================================================
135
136 To install TYPO3, unpack the source package outside of the web site root
137 directory on your server. The location must be accessible to the web server.
138 Unpacking will produce a directory with a name like typo3_src-x.y.z, where x,
139 y and z correspond to the TYPO3 version. For example, the TYPO3 4.6.0 source
140 package will create a directory named typo3_src-4.6.0.
141
142 Unpack the dummy package in the temporary location on the server. This will
143 create a dummy-x.y.z directory. Move all files and directories from the
144 dummy-x.y.z directory to the web site root directory.
145
146 Linux, Unix and Mac OS X users should use the tar.gz packages and unpack them
147 using:
148         tar xzf source-x.y.z
149         tar xzf dummy-x.y.z
150
151 Windows users can use Windows built-in unpacker on unpack ZIP versions of
152 packages.
153
154 On Linux, Unix or Mac OS X systems create a symbolic link named typo3_src
155 pointing to the source package:
156         ln -s /var/www/typo3_src-4.6.0 /var/www/example.com/typo3_src
157
158 On Windows Vista or Windows 7 create a symbolic link named typo3_src
159 pointing to the source package:
160         mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-4.6.0
161
162 Users of Windows XP/2000 or newer can use the "junction" program by
163 Marc Russinovich to create links. The program can be obtained at:
164         http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
165
166 Next create link for the typo3/ directory:
167 cd /var/www/example.com
168         ln -s typo3_src/typo3
169
170 Linux, Unix and Mac OS X users also create a symbolic link to index.php
171         ln -s typo3_src/index.php
172
173 Windows users must copy index.php from the source directory to the web site
174 root directory because Windows does not support links for files.
175
176 Change permissions and ownership of the directories. This usually requires the
177 "sudo" command. Assuming that the web server user is in the group named
178 "apache", execute the following commands in the web site root directory:
179         sudo chgrp -R apache fileadmin typo3temp typo3conf uploads
180         sudo chmod -R g+rwX,o-w fileadmin typo3temp typo3conf uploads
181
182 If "sudo" is not available, ask your hosting company to change the permissions.
183
184
185 ===============================================================================
186 Setting up TYPO3
187 ===============================================================================
188
189 To set up TYPO3, navigate to your web site. The TYPO3 installer will run in the
190 1-2-3 mode to easily guide you through the installation.
191
192
193 ===============================================================================
194 Troubleshooting
195 ===============================================================================
196
197 For troubleshooting read the FAQ below. If your problem is not listed, feel
198 free to ask questions in the TYPO3 mailing lists:
199         http://typo3.org/support/mailing-lists/
200
201
202 ===============================================================================
203 FAQ
204 ===============================================================================
205
206 Q:      Why do I get "500 Server error" when I navigate to my TYPO3 web site
207         immediately after installation?
208 A:      Make sure that AllowOverride allows "Indexes" and "FileInfo" in the Apache
209         configuration. If you cannot ensure this, rename .htaccess files to
210         _.htaccess. TYPO3 will run but considerably slower.
211         Here is the list of the files to rename:
212                 typo3/contrib/.htaccess
213                 typo3/gfx/.htaccess
214                 typo3/mod/user/ws/.htaccess
215                 typo3/sysext/.htaccess
216                 typo3/sysext/t3skin/stylesheets/.htaccess
217         If the error does not disappear, web server error logs should help. For
218         Apache, the error log is usually located in /var/log/apache2 or
219         /var/log/httpd. Check with your hosting provider if you are in doubt where
220         the logs are located.
221
222 Q:      Backend or Installer looks strange, no images just black and white?
223 A:      Maybe you missed some configuration in your .htaccess file.
224         Have a look at typo3_src/misc/advanced.htaccess to find the options
225         you might need.
226
227 Q:      I went through the setup process and created an admin user. Why can't I log
228         in now?
229 A:      If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
230         TYPO3 Install tool under http://example.com/typo3/install/ (where example.com
231         is the web site domain), navigate to "All configuration". find "setDBinit",
232         and add this line to the top of the input field:
233                 SET SESSION sql_mode='MYSQL40'
234
235 Q:      Some modules or extensions make Apache crash on Windows. What is the cause?
236 A:      Fluid uses complex regular expressions which require a lot of stack space
237         during the first processing. On Windows the default stack size for Apache
238         is a lot smaller than on unix. You can increase the size to 8MB (default on
239         unix) by adding to the httpd.conf:
240                 <IfModule mpm_winnt_module>
241                         ThreadStackSize 8388608
242                 </IfModule>
243         Restart Apache after this change.
244
245 Q:      What do I have to do regarding security?
246 A:      You have to make sure that you keep your TYPO3-core and the extensions
247         up to date.
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         * Use the scheduler task "Update Extension List (em)" to update the list of
253           available extensions regularly. You should check regularly, if new versions
254           of these extensions are available and install them respectively.
255         * For further reading regarding securing TYPO3, please read the TYPO3 security
256           cookbook and other resources. Please visit
257           http://typo3.org/teams/security/resources/