Introduction

What does it do?

This documentation explains the basics of the installation process from scratch. It aims to guide TYPO3 newbies, who read it through from beginning to end with good will and perseverance, to a working TYPO3 installation.

Depending on the operating system there are additional documentations that go into the specifics for each OS.

For advanced users or professionals it is a reference guide to look up features, links and good-to-knows.

What does it not do?

It is not, however, an installation guide for the operating system, Apache, MySQL, PHP etc. - so called LAMP or WAMP installations. Although certain changes to configuration or initialization files will be necessary, it doesn't provide an in-depth explanation of the operating system, but rather focus on TYPO3 and its configuration for running on one of them.

Who is it for?

This guide is for newbies, users, administrators and developers that like to install TYPO3 on their desired platform. Administrators and developers will need to skip part of the guide because of their technical and operational knowledge (see 'How to read this documentation' below).

What is a newbie?

Newbies are "new users". It is not a shame to be a newbie as long as it is not mistaken with lazy, ignorant or stupid. Being a newbie is a tough position, especially with TYPO3. There is so much to learn and understand, it can be overwhelming. There is a lot of reading to do, something that newcomers are asked to do before asking questions in the mailing list. Unfortunately this is frequently forgotten or disregarded.

How to read this documentation

Feel free to skip any paragraph that does not interest you. It is hard to tell how much somebody knows when they start with TYPO3 and what background they have. Where something is completely clear to a Linux administrator, it is jibberish for a web designer, and the other way around. Both should be able to learn more about TYPO3. So before you get bored with long-winded explanations, just skip to the area of your particular interest.

How TYPO3 works

If that could be answered in one paragraph then TYPO3 wouldn't be that what it is: A complete and yet flexible Content Management System (CMS).

We want to focus on the installation and that means we need to understand how TYPO3 is set up.

TYPO3 has two main parts: The Core and the Extensions. The Core is like the foundation of a building without it it will stumble and fall apart. It is the stable part and you'll most probably never need to modify the Core. The Extensions are the spice in the soup. They make TYPO3 what it is. This concept also guarantees a safe and backward compatible system even in the far future. However, that concept also makes it tricky to install, especially if you need to do it manually.

Symbolic links

Symlinks (short for symbolic links) are a great asset of *nix. They are very much like the shortcuts that you can create on your desktop (Windows, Mac etc.) that only point to a file. If you delete the shortcut the file still exists.

TYPO3 uses symlinks to offer a much easier management of future maintenance and upgrades. With symlinks your are able to install the TYPO3 core once and point to it from every new website you create. That way as soon as a new version of the TYPO3 core is out you simply upgrade the core and all the websites are upgraded at the same time.

More about symlinks and how to set up TYPO3 later in this document.

System requirements

TYPO3 is a cross platform web application and can be run on as well as used from *nix, Windows and MacOS X.

What do you need to run TYPO3? First, you need good problem solving skills, and be able to work with software at a technical level. To be able to customize your Typo3 system, programming knowledge is almost required.

If you are able to follow the step by step instructions but at the same time are not familiar with what you are doing, you are able to install TYPO3 but not skilled enough to fix something that you break in the process. Just make sure to be careful about what your are doing and keep in mind on what level you are.

In addition to TYPO3 itself, you will also require some other software to get your installation up and running.

phpMyAdmin - TYPO3 comes packaged with this tool, which enables you to administer the database from within the TYPO3 administration area. If you also want to do this from outside the TYPO3 backend, download this package from http://www.phpmyadmin.net/

Curl - If your web server is behind a proxy server, you'll need to make the appropriate configuration changes in the TYPO3 Install Tool, and install Curl, to be able to access the extension repository ( http://curl.haxx.se/ )

A lot of questions regarding Webspace, Hoster, Provider, Webserver etc. are asked in the mailing lists. Questions are mostly concerned with how to install TYPO3 on Webspace or how to get the provider to increase memory and so forth.

Let's address that issue by answering the most common questions and explaining the more or less subtle differences.

How to install

This manual uses the Install Tool which allows you to configure the vital database information for TYPO3 in three simple steps. It's meant for newbies and is automatically active if you download one of the zip-packages with complete sites. A "complete site" is a combination of the source-code and site-specific folders. Therefore this would not apply for the TYPO3 source code archives but only such downloads as the testsite or other out-of-the-box TYPO3 applications.

Check package(s)

After obtaining TYPO3 the source, you can check its authenticity by verifying the MD5 signature. You can find such signatures on the release note pages like TYPO3 4.4.2.

Upload

Upload the package(s) to your webspace. Remember that you need two packages when using the .tgz distributions.

NOTE that old 'standard' tar (ie. not GNU tar) can't handle long paths (more than 100 characters) and will probably fail unpacking the source package.

Change the name of the dummy directory to something more useful

mv dummy-x.x.x myfirsttypo3

It may be necessary to change the owner and group rights of the files you have just extracted according to your specific web server settings. For instance, on Gentoo with Apache, it is needed to change the owner and group to 'apache':

Install Tool

In the main source distribution of Typo3, the install
script is disabled by a die() function call.
Fix: Open the file typo3/install/index.php and
remove/out-comment the line that outputs this message!

or in version 4.1.2

The Install Tool is locked.
Fix: Create a file typo3conf/ENABLE_INSTALL_TOOL
This file may simply be empty.
For security reasons, it is highly recommended to rename
or delete the file after the operation is finished.

With version 4.1.2 it is really simple just create an empty "typo3conf/ENABLE_INSTALL_TOOL" with

touch typo3conf/ENABLE_INSTALL_TOOL

and it should work. If that does not work or you do not have version 4.1.2 please read the following chapters to continue with the installation.

What does that mean?

When you access your TYPO3 installation for the first time, TYPO3 redirects you to the install tool. The install tool enables you to set up TYPO3. And since we work on the internet, pretty much everybody who can access your TYPO3 site could access it too.

Of course, in our example we work locally, so only people who have access to your local network could access the install tool.

Therefore we need some security and that is what TYPO3 is providing. First step of security is that you cannot run the install tool. That what the die() function is for.

The die() function terminates the execution immediately. We need to comment out the die() function in order to start the install tool.

1. Go to the install directory.

cd /var/www/myfirsttypo3/typo3/install

[NOTE] For those without working symlinks you could also change directory to

cd /var/lib/typo3/typo3_src-3.5.0/typo3/install

Both ways you end up at the same place. The first one through several symlinks. The second one directly.

2. Open index.php in a text editor.

3. Find the die() function

4. Comment out the line by adding // or # to the beginning of the line, so it looks like this:

//die("In the main source distribution of typo3, the install script...

The Basic Configuration checks your system environment and tells you where TYPO3 has some problems. That doesn't mean that all the problems have to be fixed right away for TYPO3 to run properly but if you want to use all the features make sure the Basic Configuration runs error free.

Then you have to create a user in MySQL with these settings. You can find out in the Install Tool, 1. Basic Configuration or you see it in the error message, what user name you should use. For example, if the user reported in the error message is "mike", execute the following command in the MySQL monitor:

PHP does not feature MySQL support (which is pretty unusual)

Make sure that PHP is not using a previously installed php.ini file.

check /etc/apache2/mods-enabled/php5.conf
to see if the following lines exist

# To re-enable php in user directories comment the following lines
# (from <IfModule ...> to </IfModule>.) Do NOT set it to On as it
# prevents .htaccess files from disabling it.
<IfModule mod_userdir.c>
<Directory /home/*/public_html>
php_admin_value engine Off
</Directory>
</IfModule>

commenting the aboves lines as per instruction in the php5.conf file,
solves the problem for the TYPO3 install tool

TYPO3 with symlinked source

In case you want to use a symlinked source, please be aware that on some servers or configurations the path to typo3's home directory is not correctly resolved and all files with relative paths in TYPO3 (images, templates) are not found. So if your template seems not to work, check this and maybe try without symlinks. Also see here: [1]