Fixed bug #14367: Install Tool does not provide a logout possibility (thanks to Lars...
[Packages/TYPO3.CMS.git] / INSTALL.txt
1 *******************************************************************************
2 INSTALLING TYPO3
3 $Id$
4 *******************************************************************************
5
6 This document is a part of the TYPO3 project. TYPO3 is an open source web
7 content management system released under the GNU GPL. TYPO3 is copyright
8 (c) 1999-2009 by Kasper Skaarhoj.
9
10 This document describes the system requirements for TYPO3 and the installation
11 routine.
12
13
14 ===============================================================================
15 System requirements
16 ===============================================================================
17
18 TYPO3 requires a web server with a PHP installation and a database. While TYPO3
19 can be configured to run on many web servers with different databases, this
20 document assumes that Apache and MySQL will be used. This document does not
21 cover using TYPO3 with other databases or web servers.
22
23 The following configuration is the minimum required:
24 - a web server capable of running PHP
25 - PHP 5.2.0 or newer with the following extensions:
26         - filter
27         - GD2
28         - JSON
29         - mysql
30         - pcre
31         - session
32         - SPL
33         - standard
34         - xml
35         Some extensions can be optionally compiled into PHP. A list of loaded
36         extensions can be checked using the phpinfo() function.
37 - memory_limit set to at least to 64M in php.ini
38 - MySQL 4.1 or newer
39 - 200 MB of disk space
40 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
41   (see FAQ below)
42
43 The following configuration is recommended:
44 - Apache 2.x
45 - mod_expires and mod_rewrite enabled in the Apache configuration
46 - PHP 5.2.0 or newer with the following extensions:
47         - cURL
48         - filter
49         - GD2
50         - hash
51         - JSON
52         - mbstring
53         - mysql
54         - pcre
55         - session
56         - SPL
57         - standard
58         - xml
59         Some extensions can be optionally compiled into PHP. A list of loaded
60         extensions can be checked using the phpinfo() function.
61 - memory_limit set to 128M or more in php.ini
62 - MySQL 5.1 or newer
63 - GraphicsMagick
64 - 200 MB or more of disk space
65 - AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
66   (see FAQ below)
67
68
69 ===============================================================================
70 Obtaining TYPO3
71 ===============================================================================
72
73 To get TYPO3, navigate to the following location:
74         http://typo3.org/download/packages/
75
76 TYPO3 consists of two packages: source and dummy. The source package contains
77 files that are the same for every TYPO3 web site. The dummy package contains
78 files unique to each TYPO3 installation.
79
80 To install TYPO3, both packages must be downloaded.
81
82
83 ===============================================================================
84 Installation: simple (not recommended!)
85 ===============================================================================
86
87 This procedure is not recommended because it makes upgrades harder. However, it
88 can be the only option if you hosting company does not provide SSH access to
89 the web server.
90
91 To install TYPO3, unpack the source package locally. Unpacking will produce a
92 directory with a name like typo3_src-x.y.z, where x, y and z correspond to the
93 TYPO3 version. For example, the TYPO3 4.3.0 source package will create a
94 directory named typo3_src-4.3.0.
95
96 Next unpack the dummy package. This will create a directory with the name
97 dummy-x.y.z. Now create a new directory and copy all files and folders from
98 within typo3_src-x.y.z and dummy-x.y.z into this new directory.
99
100 Use a FTP or SFTP program or any other available way to upload all files to
101 the web server.
102
103 Change permissions of the directories and files. The following directories and
104 files should be read-only for the web server:
105         t3lib/
106         typo3/
107         index.php
108
109 All other directories should be writable for the web server. If in doubt,
110 contact your hosting company and ask them to assist in adjusting permissions.
111
112
113 ===============================================================================
114 Installation: recommended
115 ===============================================================================
116
117 To install TYPO3, unpack the source package outside of the web site root
118 directory on your server. The location must be accessible to the web server.
119 Unpacking will produce a directory with a name like typo3_src-x.y.z, where x,
120 y and z correspond to the TYPO3 version. For example, the TYPO3 4.3.0 source
121 package will create a directory named typo3_src-4.3.0.
122
123 Unpack the dummy package in the temporary location on the server. This will
124 create a dummy-x.y.z directory. Move all files and directories from the
125 dummy-x.y.z directory to the web site root directory.
126
127 Linux, Unix and Mac OS X users should use the tar.gz packages and unpack them
128 using:
129         tar xzf source-x.y.z
130         tar xzf dummy-x.y.z
131
132 Windows users can use Windows built-in unpacker on unpack ZIP versions of
133 packages.
134
135 On Linux, Unix or Mac OS X systems create a symbolic link named typo3_src
136 pointing to the source package:
137         ln -s /var/www/typo3_src-4.3.0 /var/www/example.com/typo3_src
138
139 On Windows Vista or Windows 7 create a symbolic link named typo3_src
140 pointing to the source package:
141         mklink /D C:\<dir>\typo3_src-4.3.0 C:\<dir>\example.com\typo3_src
142
143 Users of Windows XP/2000 can use the "junction" program by Marc Russinovich to
144 create links. The program can be obtained at:
145         http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
146
147 Next create links for the typo3/ and t3lib/ directories:
148 cd /var/www/example.com
149         ln -s typo3_src/t3lib
150         ln -s typo3_src/typo3
151
152 Linux, Unix and Mac OS X users also create a symbolic link to index.php
153         ln -s typo3_src/index.php
154
155 Windows users must copy index.php from the source directory to the web site
156 root directory because Windows does not support links for files.
157
158 Change permissions and ownership of the directories. This usually requires the
159 "sudo" command. Assuming that the web server user is in the group named
160 "apache", execute the following commands in the web site root directory:
161         sudo chgrp -R apache fileadmin typo3temp typo3conf uploads
162         sudo chmod -R g+rwX,o-w fileadmin typo3temp typo3conf uploads
163
164 If "sudo" is not available, ask your hosting company to change the permissions.
165
166
167 ===============================================================================
168 Setting up TYPO3
169 ===============================================================================
170
171 To set up TYPO3, navigate to your web site. The TYPO3 installer will run in the
172 1-2-3 mode to easily guide you through the installation.
173
174
175 ===============================================================================
176 Troubleshooting
177 ===============================================================================
178
179 For troubleshooting read the FAQ below. If your problem is not listed, feel
180 free to ask questions in the TYPO3 mailing lists:
181         http://typo3.org/community/mailing-lists/
182
183
184 ===============================================================================
185 FAQ
186 ===============================================================================
187
188 Q:      Why do I get "500 Server error" when I navigate to my TYPO3 web site
189         immediately after installation?
190 A:      Make sure that AllowOverride allows "Indexes" and "FileInfo" in the Apache
191         configuration. If you cannot ensure this, rename .htaccess files to
192         _.htaccess. TYPO3 will run but considerably slower.
193         Here is the list of the files to rename:
194                 typo3/contrib/.htaccess
195                 typo3/gfx/.htaccess
196                 typo3/mod/user/ws/.htaccess
197                 typo3/sysext/.htaccess
198                 typo3/sysext/t3skin/stylesheets/.htaccess
199         If the error does not disappear, web server error logs should help. For
200         Apache, the error log is usually located in /var/log/apache2 or
201         /var/log/httpd. Check with your hosting provider if you are in doubt where
202         the logs are located.
203
204 Q:      I went through the setup process and created an admin user. Why can't I log
205         in now?
206 A:      If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
207         TYPO3 Install tool under http://example.com/typo3/install/ (where example.com
208         is the web site domain), navigate to "All configuration". find "setDBinit",
209         and add this line to the top of the input field:
210                 SET SESSION sql_mode='MYSQL40'