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