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