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