Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

TYPO3 Installation Basics

From TYPO3Wiki
Jump to: navigation, search

<< Back to Getting started page

[edit]

Outdated This information is outdated. While some details may still apply in specific situations, this page was written for obsolete versions of TYPO3. You should read the official Installation and Upgrade Guide instead!


Note This text was originally written by Jean-Marie Schweizer in 2004.

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.

What already exists

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.

[NOTE]: Windows (2000, XP and 2003) can work with symlinks but needs an additional freeware: Junction Tool from Sysinternals.com or by using linkd.exe utility available in the Windows Resource Kit or here - http://www.petri.co.il/download_free_reskit_tools.htm

Read also the Instructions about Symlinks on Windows.

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.

The following list should help to get you started: (see also [requirements on typo3.org])

Optionally you can download and install some of the following software depending on how you are going to use TYPO3:

  • GraphicsMagick/ImageMagick - For image operations. Get either from http://www.graphicsmagick.org/download.html or http://www.imagemagick.org/script/download.php
  • GD/FreeType (compiled into PHP)- From http://www.boutell.com/gd/ and from http://www.freetype.org/
  • A PHP opcode cache a.k.a. PHP accelerator like APC, XCache or eAccelerator
  • zlib - This is compiled into PHP and is used to compress/decompress while importing/exporting .t3x files, and speeds up interaction with the TER (Typo3 Extension Repository)
  • The Apache extensions mod_deflate/mod_gzip and mod_rewrite (docs are at http://httpd.apache.org/docs/)
  • 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/ )

You'll find out more details about the requirements here:

Webspace vs. Webserver

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.

Before you start

Before you start with the installation process you should make sure that you know what you want to accomplish and that you are in the possession of the right tools, files etc.

You also should know about your system enviroment and it doesn't hurt to have studied some basics about TYPO3.

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.

Unpack .tgz packages

Follow these steps to unpack TYPO3 on a *nix server:

1. Unpack the packages in your web space. Don't forget the p flag to tar, which instructs tar to preserve the archives file attributes.

tar xzpvf <typo3_src-x.x.x.tar.gz>
tar xzpvf <dummy-x.x.x.tar.gz>

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':

chown -R apache:apache <typo3_src-x.x.x>
chown -R apache:apache <myfirsttypo3>

On Debian (and Ubuntu) you can use

chown -R www-data:www-data <typo3_src-x.x.x>
chown -R www-data:www-data <myfirsttypo3>

On Arch Linux you can use

chown -R http:http <typo3_src-x.x.x>
chown -R http:http <myfirsttypo3>

You are now ready to start installing TYPO3. The myfirsttypo3 directory will be the base directory for your new web site!

Change site directory

If you don't want to have your site in a subdirectory, you can move all files from the subdirectory up to the directory where your .tgz files are located:

cd dummy-x.x.x
mv * ..
cd ..

You also have to "rename" one of the symlinks:

rm typo3_src
ln -s ./typo3_src-x.x.x typo3_src

Now list the contents of the directory and see that it has the following files/symlinks. If one of them is missing, your installation will probably fail:

ls -l
-rw-r--r--   1 user   user       4937 Sep 24 13:06 INSTALL.txt
-rw-r--r--   1 user   user         46 Sep 24 13:06 clear.gif
drwxr-xr-x   2 user   user       4096 Oct 14 19:26 dummy-4.1.1
drwxrwxrwx   4 user   user       4096 Sep 24 13:06 fileadmin
lrwxrwxrwx   1 user   user         18 Oct 14 19:22 index.php -> typo3_src/index.php
lrwxrwxrwx   1 user   user         15 Oct 14 19:22 t3lib -> typo3_src/t3lib
lrwxrwxrwx   1 user   user         15 Oct 14 19:22 typo3 -> typo3_src/typo3
lrwxrwxrwx   1 user   user         18 Oct 14 19:22 typo3_src -> typo3_src-4.1.1
drwxr-xr-x   5 user   user       4096 Sep 24 13:06 typo3_src-4.1.1
drwxrwxrwx   3 user   user       4096 Sep 24 13:06 typo3conf
drwxrwxrwx   2 user   user       4096 Sep 24 13:06 typo3temp
drwxrwxrwx   6 user   user       4096 Sep 24 13:06 uploads


Important: Before TYPO3 4.0beta3 this directory listing should look like this instead:

-rw-r--r--   1 user   user       4937 Sep 24 13:06 INSTALL.txt
-rw-r--r--   1 user   user         46 Sep 24 13:06 clear.gif
drwxr-xr-x   2 user   user       4096 Oct 14 19:26 dummy-3.7.0
drwxrwxrwx   4 user   user       4096 Sep 24 13:06 fileadmin
lrwxrwxrwx   1 user   user         18 Oct 14 19:22 index.php -> tslib/index.php (1)
lrwxrwxrwx   1 user   user         11 Oct 14 19:22 media -> tslib/media (2)
lrwxrwxrwx   1 user   user         17 Oct 14 19:22 showpic.php -> tslib/showpic.php (2)
lrwxrwxrwx   1 user   user         15 Oct 14 19:22 t3lib -> typo3_src/t3lib
lrwxrwxrwx   1 user   user         15 Oct 14 19:22 tslib -> typo3_src/tslib (2)
lrwxrwxrwx   1 user   user         15 Oct 14 19:22 typo3 -> typo3_src/typo3
lrwxrwxrwx   1 user   user         18 Oct 14 19:22 typo3_src -> typo3_src-3.7.0
drwxr-xr-x   5 user   user       4096 Sep 24 13:06 typo3_src-3.7.0
drwxrwxrwx   3 user   user       4096 Sep 24 13:06 typo3conf
drwxrwxrwx   2 user   user       4096 Sep 24 13:06 typo3temp
drwxrwxrwx   6 user   user       4096 Sep 24 13:06 uploads

(1) Starting with TYPO3 4.0beta3 this symlink should point to typo3_src/index.php.

(2) Starting with TYPO3 4.0beta3 these symlinks are not needed anymore.

More on different servers

Linux/Unix

Other

Install Tool

When you access your TYPO3 installation, for example from

http://192.168.1.25/myfirsttypo3/typo3/install

you end up with the following message:

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...

5. Save and exit.

6. Try to access myfirsttypo3 again.

http://192.168.1.25/myfirsttypo3

[NOTE] 192.168.1.25 stands for the IP address of the webserver. It can be anything the points to your TYPO3 site.

[NOTE] You can start the Install Tool in 123-mode manually by entering the following URL:

http://192.168.1.25/myfirsttypo3/typo3/install/index.php?mode=123&step=1&password=joh316

1-2-3-GO Installation

Once you remove the die() function the install tool greets you with the following message:

InstallTollMessage.png

Remember the temporary password joh316 and read all instructions carefully.

Press <Ok> to continue

The first step of the TYPO3 install tool is to configure that MySQL database that is used for your TYPO3 site.

[NOTE] If you haven't set the MySQL root password, a database or a user yet, go to the MySQL configuration and MySQL Installation and setup section. (docs will be joined later)


1. Enter your username and password for MySQL.

Typo3inst123mysql.png

[NOTE] When you enter the passwod it will show it clearly not with * as in the picture.

Press the button <Update localconf.php>.

Typo3inst123mysql2.png

2. Enter a database name to create a new database, e.g. myfirsttypo3

Press the button <Update localconf.php>.

[NOTE] Don't use the mysql or test database of the existing databases since they are used internally by MySQL.

Typo3inst123mysql3.png

You get to see an overview of your MySQL information (again instead of the * you see your password).

3. Import the standard database. Keep the selection of database.sql.

Press the button <Import database>. 

Typo3inst123go.png

Configure TYPO3

Set New Install Password

1. Click Continue to configure TYPO3 to continue with the installation process

2. Enter a password for the install tool and press the button <Set new password>.

Typo3instpassw.png

3. Choose 1. Basic Configuration in the menu.

4. Enter your new install tool password.

5. Press the button <Log in>.

Check Basic Configuration

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.

Database Analyser

Image Processing

If ImageMagick is installed and tested correctly, you should see something like this.

Image Processing contains five tests:

  1. Reading image formats
  2. Writing GIF and PNG
  3. Scaling images
  4. Combining images
  5. GD library functions

All Configuration

typo3temp

Clean up database

phpinfo()

Edit files in typo3conf/

About

Start TYPO3

Now it is time to test TYPO3 by starting the Backend (BE).

Login

You login to the TYPO3 backend at http://yourdomain/typo3 with the username "admin" and password "password".

Change password

The first thing you should do is change the password to something more unique!

Troubleshooting

SQL safe mode

If sql.safe_mode is enabled, mysql_connect() and mysql_pconnect() ignore any arguments passed to them. Instead, PHP attempts to connect using the following details:

  • host: localhost
  • user: the user PHP runs as
  • password: an empty string ("")

This could cause the Install Tool to display an error message like this

Warning: Access denied for user: 'mike@localhost' (Using password: NO) in 
/var/www/typo3_src-3.7.0/t3lib/class.t3lib_db.php on line 813

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:

mysql> INSERT INTO user (host, user, password) 
    -> VALUES ("localhost", "mike", "");

or update a present user with the following:

mysql> UPDATE user SET host="localhost", password=""  
    -> WHERE user="mike";

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]