Installation and Upgrade Guide

Previous Key:doc_guide_install
Version:latest (8-dev)
Language:en
Description:This document describes the file structure of TYPO3 and takes you step by step through the installation. It does not focus on specific operating systems, but contains some hints on general TYPO3 installation issues with regards to Apache, PHP and MySQL.
Keywords:forAdmins, forBeginners
Copyright:2000-2015
Author:Documentation Team
Email:documentation@typo3.org
License:Open Publication License available from www.opencontent.org/openpub/
Rendered:2018-02-13 11:48

The content of this document is related to TYPO3,

a GNU/GPL CMS/Framework available from www.typo3.org

Official documentation

This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3 Documentation Team following a peer review process. The reader should expect the information in this document to be accurate; please report discrepancies to the Documentation Team (documentation@typo3.org). Official documents are kept up-to-date to the best of the Documentation Team's abilities.

Guide

This document is a Guide. Guides are designed to familiarize a reader with a specific topic in order to provide a working knowledge of that particular process. Readers should peruse the guide from cover to cover in order to gain a practical overview of the process. Once completed, the Guide becomes a practical reference tool to which a reader can refer as needed. Guides offer advice on how best to achieve a given task.

Table of Contents

Introduction

About this document

This manual gives you an introduction on how to install or upgrade your TYPO3 CMS installation.

The "Installation" section is aimed at beginners who want to get a fresh TYPO3 CMS website up and running. The "Update" section targets those who already have a running website and want to migrate it to a newer version of TYPO3 CMS.

You must go through the steps in the section "Quick Installation" in order to get your TYPO3 installation up and running. During or after that, you have the option go through the section "In-Depth Installation" to configure TYPO3 in more detail.

What's new

Updated the manual for TYPO3 CMS version 8.7.

Credits

This manual was originally written by Kasper Skårhøj and is now kept up to date by the documentation team.

Feedback

For general questions about the documentation get in touch by writing to documentation@typo3.org .

If you find a bug in this manual, please be so kind as to check the online version on https://docs.typo3.org/typo3cms/InstallationGuide/. From there you can hit the "Edit me on GitHub" button in the top right corner and submit a pull request via GitHub. Alternatively you can just file an issue using the bug tracker: https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-Installation/issues.

Maintaining high quality documentation requires time and effort and the TYPO3 Documentation Team always appreciates support. If you want to support us, please join the documentation mailing list/forum (http://forum.typo3.org/index.php/f/44/) or the slack channel #typo3-documentation.

Quick Installation

The following instructions assume you are able to create symlinks on the target machine.

Pre-Requisites:
  • Running web server (Apache, Nginx, IIS...)
  • PHP > 7 installed

Install TYPO3 via composer

The recommended way of installing TYPO3 is via composer.

To create a new TYPO3 project use the TYPO3 Base Distribution:

# Download the Base Distribution, the latest "stable" release (8.7)
composer create-project typo3/cms-base-distribution YourNewProjectFolder

Note

To install TYPO3 via composer on windows composer should be started as admin or explicitly given the right to create symlinks.

After installation continue with the steps in The Install Tool

Get and Unpack the TYPO3 Package

Installing on a Unix server

  1. Get the Source Package from http://typo3.org/download/ and upload this package to your web server. Put it one level above the document root. For this manual, we will use the .tar.gz file. (If you are not sure which package you should choose, read the section "Which Package and which Format?" in the in-depth part of the manual). Use the shell to execute the according commands:

    /var/www/site/htdocs/$ cd ..
    /var/www/site/$ wget get.typo3.org/8.7 -O typo3_src-8.7.x.tar.gz
    
  2. Unpack the typo3_src-8.7.x.tar.gz file on your web server:

    /var/www/site/$ tar xzf typo3_src-8.7.x.tar.gz
    

    Note

    Be aware that the x in the extracted folder will be replaced with the latest bugfix version, e.g. typo3_src-8.7.8.

    Tip

    You can also unpack the package on your local PC and then upload the unpacked contents. However, the package contains thousands of files, so if you're able to unzip or untar the package on the server, better do that!

  3. Create these symlinks in your document root:

    cd htdocs
    ln -s ../typo3_src-8.7.x typo3_src
    ln -s typo3_src/index.php index.php
    ln -s typo3_src/typo3 typo3
    
  4. Create an empty file FIRST_INSTALL to enable the Install Tool to set up and configure the instance in the next step:

    touch FIRST_INSTALL
    
  5. In case you use the Apache web server, copy the .htaccess file to your document root:

    cp typo3_src/_.htaccess .htaccess
    

    You end up with the following structure of files:

    typo3_src-8.7.x/
    htdocs/typo3_src -> ../typo3_src-8.7.x/
    htdocs/typo3 -> typo3_src/typo3/
    htdocs/index.php -> typo3_src/index.php
    htdocs/.htaccess
    htdocs/FIRST_INSTALL
    

The advantage of this setup is that all files from the TYPO3 Source package are kept together in the typo3_src-8.7.x folder and separated from other files of your installation. This allows you to easily exchange this folder when a new patchlevel version of TYPO3 is released.

Note

This setup allows the administrator to use the "Core Updater" feature in the Install Tool to later easily update the TYPO3 Source files.

Installing on a Windows server

  1. Get the Source Package from http://typo3.org/download/ and extract it on your local PC. Use FTP, SFTP or similar to upload the contents of this package to your web server. Put them one level above the document root. For this manual, we will use the .zip file. (If you are not sure which package you should choose, read the section "Which Package and which Format?" in the in-depth part of the manual).

  2. Use the shell to create these symbolic links in your document root:

    cd htdocs
    mklink /d typo3_src ..\typo3_src-8.7.x
    mklink /d typo3 typo3_src\typo3
    mklink index.php typo3_src\index.php
    
  3. In case you use the Apache web server, copy the .htaccess file to your document root:

    copy typo3_src/_.htaccess .htaccess
    

    You end up with the following structure of files:

    typo3_src-8.7.x/
    htdocs/typo3_src -> ../typo3_src-8.7.x/
    htdocs/typo3 -> typo3_src/typo3/
    htdocs/index.php -> typo3_src/index.php
    htdocs/.htaccess
    

The Install Tool

  1. Hit the start page of your freshly created site with your browser and you should see the "thank you for downloading"-message.

    Success message after download.

    Success message after download.

  2. Create the file FIRST_INSTALL in your web root directory and reload the page. You will be redirected to the install tool. It will guide you through the steps for installing TYPO3. The Install Tool is located in 'typo3/install' in your installation which for example would be http://www.example.com/typo3/install/.

  3. This is what you should see:

    first step

    Install Tool in 1-2-3 mode, first step.

  4. In case you have problems in your Environment, you will get warnings or hints in this screen. In this case, you should try to fix them; the "Troubleshooting" section might help you.

  5. Enter your database credentials. Enter MySQL username and password. In most cases the database host is "localhost".

    second step

    Install Tool in 1-2-3 mode, second step.

  6. Create a new database for TYPO3 or use an existing empty database.

    third step

    Install Tool in 1-2-3 mode, third step.

  7. Enter a username and password for your first TYPO3 admin user. (For security reasons, it's best not to use the name admin.) This password will also be configured for the Install Tool. The "site name" will identify this installation (in the page tree and browser title).

    forth step

    Install Tool in 1-2-3 mode, forth step.

  8. In the last step you can choose whether you want to start with an empty TYPO3 or if you want to have a basis to start from.

    fifth step

    Install Tool in 1-2-3 mode, fifth step.

  9. The basic installation is now complete!

After the basic installation procedure is complete, TYPO3 will be working and the most appropriate settings will have been made for you. You will get redirected to the Backend and can log in with your admin user account.

If you want to make changes to your installation settings at a later date, use the "Install Tool". You can find more information in the section "In-Depth Installation", subsection "The Install Tool" below.

In-Depth Installation

System Requirements

TYPO3 requires a web server, PHP and a database system.

  • TYPO3 requires a web server which can run PHP (e.g. Apache, Nginx or IIS).
  • TYPO3 8 requires at least PHP 7.x.
  • TYPO3 can be used with a great many database systems (e.g. MySQL or Postgres). If you use MySQL, you will need to install at least MySQL 5.5.

If you use an Apache web server, the module mod_rewrite must be activated. Certain PHP extensions are necessary, others recommended. You possibly want to adjust the memory limit; at least 128 MB is recommended.

If you want TYPO3 to automatically carry out image processing – for example scaling or cropping – you will need GraphicsMagick or ImageMagick (version 6 or newer) installed on the server.

A detailed list of these requirements is enclosed in the file INSTALL.md inside the TYPO3 source package.

Should you encounter problems, the "Troubleshooting" section at the end of this document will help.

Which Package and which Format?

It is recommended to install TYPO3 via the PHP package manager composer. See Install TYPO3 via composer. If you are not able to use composer for your project, download the source package from https://typo3.org/download/.

Which File Format to use

The TYPO3 Source package is available as a .zip or .tar.gz distribution. Their content is the same and you should download the one that you will be able to extract directly on your web server (Windows based systems are more likely to use the .zip file while Linux distributions tend to use the .tar.gz file.

The Package in Detail

TYPO3 Folders and Files

The following files and folders are part of the TYPO3 package. In case of a composer based installation, only the necessary files will be linked in the web root. You can find the full package in vendor/typo3/cms/.

typo3/
contains the TYPO3 source code, files, images and scripts distributed with TYPO3.
index.php
the main script for the website Frontend
_.htaccess
contains an example configuration for Apache web servers, which can improve performance. It is not used by default. To activate it, copy the file to .htaccess in your document root.
NEWS.md
describes what has changed in the TYPO3 Source since the last major version. Read this carefully if you are going to update your system!
INSTALL.md
contains system requirements and a short installation how-to.

All these files are part of the TYPO3 Core. You should never change them and you can make them write-protected, if you like! They are the ones you must upgrade when you install a new version of TYPO3.

Site specific Folders and Documents

The following files and folders will be created during the installation of TYPO3:

fileadmin/
contains your site assets and files, local to the website. You can e.g. put images, user uploads and other assets here. By default this folder is used to store files, which have been uploaded in the TYPO3 Backend (fileadmin/ is configured as the first default storage). fileadmin/ must be writable for the web server user. Files in fileadmin/ are for editors, you should not put any site configuration files here. Exclude the fileadmin/ folder from your version control to make sure not to mix development files and user files.
typo3conf/
contains configuration, extensions and translations for the local site.
typo3conf/ext/
will hold the local extensions available for this installation. Can be managed through the Extension Manager.
typo3conf/l10n/
will hold translations for the TYPO3 Backend of this installation.
typo3conf/LocalConfiguration.php
is the main configuration file of your installation and the one the customized values of all the Install Tool options get written to. It has to be writable and will be updated automatically by the Install Tool and the Extension Manager. You can edit this file manually, but make sure you keep the PHP syntax working.
typo3conf/PackageStates.php
contains information about the extensions, which are available in your system.
typo3conf/AdditionalConfiguration.php
is an additional configuration file, which is executed on every request after the LocalConfiguration.php has been loaded. It can be used to manipulate the configuration of $GLOBALS['TYPO3_CONF_VARS']. This file is not created automatically; create it, if you need it.
typo3temp/
will be empty at the beginning. But gradually temporary files will appear here. The directory must be writable for the web server user.
uploads/
(deprecated) contains folders used to store documents attached to database records, hence must be writable by the web server. This folder is used for compatibility reasons with older TYPO3 releases and extensions. Newer extensions and the TYPO3 core do not use this folder anymore; instead files should be managed by the File Abstraction Layer inside the default storage (fileadmin).

Custom folders?

Yes, just add whatever you like. Why not?

The Install Tool

The Install Tool provides tools to help you with the maintenance of your installation: Upgrading, checking the system environment, configuring settings from $TYPO3_CONF_VARS and solving problems. Its usage is not dependent on a working Backend, and you access it using a single password.

First go to your site and enter the install tool (http://www.example.com/typo3/install).

Hint

If you see a message "The Install Tool is locked", create a new file named "ENABLE_INSTALL_TOOL" in the folder typo3conf/. Then reload the page.

Important actions

The section provides basic information about your system and several functions which you need for maintenance tasks or during an upgrade.

Important Actions

The "Important Actions" section of the Install Tool.

The Database analyzer can be used to compare the current structure of your database with the expected structure for the TYPO3 version you are using. The next step allows you to update the structure of your database accordingly.

The Clear all Cache functionality can empty all caches: Frontend, Backend and language caches.

The Check for broken extensions can be run to make sure that all ext_tables and ext_localconf files contain valid PHP code, so that they can be loaded without breaking the system.

The TCA Migrations can be used to check whether the current TCA needs migrations and displays applied migrations.

The Core update can update the TYPO3 Core to the newest minor version.

Apart from these functions, this section also contains options to change the install tool password, to change the site name, to change the encryption key and to create a Backend administrator user. Usually you do not need these functions.

Configuration presets

This section provides default settings for different setups.

The section "Debug settings" allows you to activate debugging. E.g. if set to "Debug", all kinds of error reporting, debugging and deprecation logging will be activated. If set to "Live", all these settings will be deactivated.

The "Image handling settings" contain presets for different image processing programs (namely ImageMagick and GraphicsMagick). Select the one you have available.

The preset "Extbase object cache" allows you to choose the kind of caching system for Extbase (a TYPO3 Extension Building Framework) to use.

Finally, in the "Mail Handling Settings" you can configure how TYPO3 sends mails (via SMTP or sendmail for example).

All configuration

Here you can configure all installation options concerning your TYPO3 installation. We suggest you go through the whole list and read the description of the settings carefully at least once, so you get an impression of what you can configure. Normally you can, but you don't have to change anything here during installation, as the previous steps took care of the most important settings.

Upgrade wizard & Upgrade Analysis

You don't need the upgrade wizard while installing TYPO3. These functions will be explained in a later chapter about upgrading TYPO3.

System environment

The section contains a huge number of environment checks, which notify you of (potential) problems in your installation. It checks Apache settings and the status of important PHP modules and PHP settings. It also contains full output of phpinfo() and some constants used by TYPO3.

Folder structure

This section shows whether the files and folders in your installation have the correct permissions. This is important so that TYPO3 can function properly and so that other users on the web server do not get access to (possibly confidential) data.

Test setup

The section "Test setup" contains a test for the mail function and for image processing. Try each test to see if you have configured your image generation settings correctly. If you have problems, check the explanation of the test for a hint on how to solve them. Additionally, have a look at the image processing settings in the section "All configuration".

You might also find help in the Troubleshooting section below.

Clean up

You don't need this section whilst installing TYPO3. This section is meant to provide methods to clean up your TYPO3 installation after it has been running for a while. You can use it to delete cached images, which is helpful when you are configuring the image processing settings. This section is also relevant during an upgrade.

The Distributions

Several Distributions are available for TYPO3 for use in your installation. In essence, a Distribution is an extension which sets up and configures TYPO3 to get you started. A Distribution often creates an example page structure and content elements, as well as automatically handling the installation and activation of useful extensions like RealURL.

If you selected the option to load preconfigured Distributions during the final step of the installation process (in the Install Tool), you will be redirected to the "Get preconfigured distribution" screen of the Extension Manager after logging in to the backend. You can also navigate there manually, of course.

Note

If you installed TYPO3 via composer all extension downloads as well as distribution installations have to be done via composer command line, too.

Amongst non-core options, the following Core Distribution is available:

Introduction Package

The Introduction Package is a complete demo website. It it based on a responsive design using bootstrap templates and contains a lot of default content for testing and learning. Try this one if you are new to TYPO3.

Introduction Package

The Introduction Package provides a full website based on bootstrap.

Installing Distributions without composer

For testing and learning we recommend that you use the Introduction Package, but several other distributions are available.

Move to the ADMIN TOOLS > Extensions module and choose "Get preconfigured distribution" from the menu in the docheader. Just choose the Distribution you would like to use and hit the "Install" button.

If you want to build your web site from scratch, just go ahead without using a Distribution. You can then start with a completely empty installation of TYPO3.

Installing Distributions with composer

To install the introduction package or any other distribution on a composer based installation use composer require typo3/cms-introduction (change the package name to the distribution you want). Afterwards use the following commands to activate the extension(s) via command line:

.vendor/bin/typo3 extensionmanager:extension:install bootstrap_package
./vendor/bin/typo3 extensionmanager:extension:install introduction

In this case, the introduction package depends on the bootstrap_package, so both packages have to be installed.

On Windows: Use use .vendorbintypo3.bat instead.

Translating the Backend

In order to use translations in the TYPO3 Backend, you first need to download the translations and then select them for the Backend users.

Download Translations for the Backend

Log in to the Backend and go to the Backend module "Language".

In the section "Languages" select the language(s), which you want to have available for use in the Backend.

After that click "Update from repository" to update the translations. This may take some time. Some extensions do not have translatable texts and so also do not have translations available. If for an extension you get an error message, wait until the update has finished and then press "Update from repository" again.

When later you install new extensions you might see that those are displaying in English only. In that case you can click on "Not checked" next to the according extension to only download the translation for this one extension. Alternatively you can repeat the steps above to get the newest translations for all extensions.

Change the Language for a Backend User

The Backend can be displayed in different languages for different users. Go to the module "User settings". On the tab "Personal data" you can choose between the languages, which you downloaded in the last step. Select the language, which you want to use. Then click "Save Configuration" and after that reload the Backend.

When you are logged in as an administrator, you can also modify user settings of other users: In the module "User settings" go to the tab "Admin functions" and select the Backend user, which you want to edit from the list. After that you can set user settings for this user and adjust his language as well.

Upgrade

When a new version of TYPO3 is released, you should follow the guideline in this chapter in order to do an upgrade. Also follow any additional upgrade information carefully. You might e.g. want to skim the ChangeLog to see if any features affect the way your site works.

Note

Version specific upgrade notes

While this guide is the general guideline to follow for a TYPO3 Upgrade, some version specific information are additionally available in the TYPO3 Wiki. Use them as an amendment to this guide!

Note

Think of active users

Think of users who might want to do any changes during your upgrading and/or fallback. Inform them before you start!

Basically these are the steps to be done to update your TYPO3 site:

Preparation

Before you start

Before starting the upgrade check your system for compatibility with a newer TYPO3 version.

  • Enable the deprecation log and let it run for a while while the website is used to catch all deprecations
  • Check installed extensions for versions compatible to the target TYPO3 version
  • Try the upgrade on a development system first!

Handling deprecations

TYPO3 promises a certain amount of backwards-compatibility between versions:

  • Minor versions are always backwards-compatible
  • Major versions may contain breaking changes - normally these are deprecated in the version before

Here is an example. If the TYPO3 team decides that an API method is no longer useful and should be removed they will first add a deprecation notice for the next major version and will remove that method only in the major version after that. So for example a method getting deprecated in version 9 will only be removed in version 10.

This methodology gives you one major version (usually 1 1/2 years) advance notice of any changes you need to make to your code to stay compatible to coming TYPO3 versions.

If you notice some API you are using is deprecated, you should look up the corresponding changelog entry and see how to migrate your code corresponding to the documentation.

Read where to find deprecation documentation in the chapter about Check the ChangeLog.

Backup

Make a backup first! If things go wrong, you can at least go back to the old version. You need a backup of

  • all files of your TYPO3 installation (by using FTP, SCP, rsync, or any other method)
  • the database (by exporting the database to an SQL file)

Also you may prefer to upgrade a copy of your site first, if there have been a lot of changes and some of them might interfere with functions of your site. See the ChangeLog to check that.

Reference Index

Still in your old TYPO3 version, go to the "System" > "DB check" module and use the "Check and update global reference index" function.

Click on "Update reference index" to update the reference index.

Install the new Source

Upgrade the distributed source files to the new version. You can do this either using the Core updater, via composer or manually.

Using the Core Updater

The Install Tool in the section "Important Actions" provides a function to update the TYPO3 Core. For this to work, the following setup is required:

  • It only works under Unix and MacOS (needs symlink support).
  • typo3_src must be a symlink.
  • This symlink needs to be writable (and deletable) by the web server user.
  • document root needs to be writable.
  • One path above document root (../) needs to be writable (new directories need to be allowed to be created).
  • The tar command must be available for extracting the Source package.

In the section "Important Actions" scroll down to "Core update" and click the "Check for core updates" button. If above requirements are met, TYPO3 will automatically install the new source code.

Note

Disabling the Core Updater

The Core Updater functionality can be disabled (in order to avoid users using it, i.e. if you use your own update mechanism). To disable the core updater, you can set this environment variable:

TYPO3_DISABLE_CORE_UPDATER=1

For example in Apache:

SetEnv TYPO3_DISABLE_CORE_UPDATER 1

or for nginx:

server {
  location ~ path/to/it {
    include fastcgi_params;
    fastcgi_param TYPO3_DISABLE_CORE_UPDATER "1";
  }
}

This will disable the button and all related functionality in the Install Tool.

If you cannot use the Core Updater, you can still install the new source code manually.

Installing the source manually

Go to http://typo3.org/download/ and download the Source package of the new TYPO3 version.

Extract the package on your web server and - in your TYPO3 document root - adjust the typo3_src symlink.

Upgrading a composer based system

Use composer to update your system via composer require typo3/cms:^8.7 --update-with-dependencies

If you have extensions installed, you will have to find the corresponding newer versions you want to install for your new major version and update them, too.

Example:

composer require typo3/cms:^8.7 georgringer/news:^6.1 --update-with-dependencies

To find the matching extension versions you can go to packagist.org, search for your extension and take a look at the requires section.

extension on packagist

The "News" extension on packagist

What's the next step?

In case you did a minor update, e.g. from TYPO3 8.7.6 to 8.7.7, database updates are usually not necessary. All you still have to do is to remove the temporary cache files. After that your update is finished.

In case of a major update, e.g. from TYPO3 7.6 to 8.7, go ahead with the next step!

Convert global Extensions

If you use global extensions, convert them to local ones.

Global extensions used to be saved in folders inside typo3/ext/, such as typo3/ext/realurl. In current versions of TYPO3, this location should no longer be used. Instead, use local extensions below typo3conf/ext/.

To convert a global extension to a local one, do the following:

  • Go to the Extension Manager.
  • Uninstall the global extension.
  • Delete the files of the extension from typo3/ext/, including the directory of that extension itself.
  • Reinstall the extension from TER, which will put it into typo3conf/ext/.

Use the upgrade wizard

Enter the Install Tool at http://yourwebsite.com/typo3/install/ on your TYPO3 site.

(If you don't know the current Install Tool password, you can set a new one by entering one in the Install Tool login screen, hitting enter and then setting the displayed hash as value of ['BE']['installToolPassword'] in typo3conf/LocalConfiguration.php.)

Upgrade wizard

The Upgrade Wizard in the Install Tool.

TYPO3 provides an upgrade wizard for easy upgrading. Go to the "Upgrade Wizard" section and take a look at the different wizards provided. You should go them through one by one.

You must start by using the "Update database schema: Create tables and fields" wizard if it's displayed, which adds new tables and columns to the database.

Click "Execute". Now all ext_tables.sql files from core and extensions are read and compared to your current database tables and columns. Any missing tables and columns will be shown and you'll be able to execute queries sufficient to add them.

After you added these tables and columns, go on to the next wizard.

The "Version Compatibility" wizard sets the compatibility version of your TYPO3 installation to the new version. This allows your Frontend output to use new features of the new TYPO3 version.

Note

This wizard might affect how your website is rendered. After finishing the upgrade, check that your website still displays the way it is supposed to be and adjust your TypoScript if necessary.

Go through all wizards and apply the (database) updates they propose. Please note that some wizards provide optional features, like installing system extensions (for example simulatestatic) that you may not need in your current installation, so take care to only apply those wizards, which you really need.

After running through the upgrade wizards go again to the Database Analyzer. You will be able to execute queries to adapt them so that the tables and columns used by the TYPO3 Core correspond to the structure required for the new TYPO3 version.

Run the Database Analyzer

Now you can use the section "Important actions" to compare the structure of your database with the expected structure. While in the previous step, tables and columns have been changed or added, this step now gives you the possibility to remove old and unneeded tables and columns from the database. Click "Compare current database with specification".

The Database Analyzer before analyzing the database.

You will be able to execute queries to remove these tables and columns so that your database corresponds to the structure required for the new TYPO3 version.

Warning

Be aware if you have deliberately added columns and/or tables to your TYPO3 database for your own purposes! Those tables and columns are removed only if you mark them to be deleted of course, but please be alert that you don't delete them by mistake!

In the next step the changes you applied don't show up again. If you chose to delete some columns or tables, you will see that they have only been renamed. Now you can consider to let them be and delete them later when you're sure you're not going to need them. Or you can mark them again and drop them finally.

If you made TYPO3 apply all changes, you should after clicking "Execute" see a notice like this:

Database analyzer

The Database Analyzer after successfully updating all table and field definitions.

When you then click "Compare current database with specification" again and you only see the message

Database analyzer

The Database Analyzer with no updates to do.

then all database updates have been applied.

Clear Caches and User Settings

You should always clear the cache tables. Go to "Clean up", scroll down to "Clear tables" and select the tables beginning with "cache_". Then press "Clear selected tables".

You might also consider clearing the Backend user preferences. This can avoid problems, if something in the upgrade requires this. Go to "Clean up", scroll to "Reset user preferences" and click "Reset backend user preferences".

Remove temporary cache files

In typo3temp/Cache/Code/cache_core you will most likely find files named ext_localconf_*.php or ext_tables_*.php. These files must be removed as well.

Go to "Important actions" and click "Clear all cache":

Clear all Cache

The option "Clear all Cache" in the Install Tool.

This method will remove all files from the folder typo3temp/Cache/Code/cache_core/.

Additionally, after an upgrade to a new major version, you should also delete the other temporary files, which TYPO3 saves in typo3temp/. In the Install Tool go to "Clean up" to do so.

Check the ChangeLog

Look through the ChangeLog online The ChangeLog is divided into four sections "Breaking Changes", "Features", "Deprecation" and "Important". Before upgrading you should at least take a look at the sections "Breaking Changes" and "Important" - changes described in those areas might affect your website.

The detailed information contains a section called "Affected Installations" which contains hints whether or not your website is affected by the change.

You can also find the ChangeLog in the Install Tool at "Upgrade Analysis". Here you can mark files as read after checking them, so you get a ToDo list for the upgrade.

Uprade Analysis

The "Uprade Analysis" in the Install Tool

Update Extensions (only on non-composer installations)

In the Backend, go to the extension manager and update the extensions you use. TYPO3 CMS stores a reference list of available extensions locally, so make sure that the list is up-to-date by clicking the "Update now" button in the "Get extensions" view.

You can also take this opportunity to delete all unused extensions, thereby making sure that there are no potential security "holes" in files stored on your server.

Update Translations

In the Backend, go to the module "Language" and update your translations. If you don't update your translations, new texts will only be displayed in English to you. (The translations are available, after the Translation Team for your language has translated the texts.)

Upgrade from LTS to LTS

This chapter provides in depth information about how to update from TYPO3 7.6 LTS to the TYPO3 CMS 8.7 LTS version.

This chapter will give you a perspective on relevant changes since TYPO3 7.6 and what to expect from the migration from 7.6 to 8.7.

Precondition

  1. TYPO3 Version

    Make sure your installation is running at least TYPO3 7.6 LTS. The TYPO3 8.7 upgrade process is possible from version 7.6 - not from older versions.

    If you are running a lower version of TYPO3, please upgrade to 7.6 first.

LTS Upgrade Process

Do the upgrade as described in the previous chapter. When you use the "Upgrade Wizards" note the following:

  • The upgrade wizard, which installs extension compatibility7 from TER, is not necessarily needed. It provides a compatibility layer for extensions, which are compatible with TYPO3 7.6, but not yet with TYPO3 8.7, e.g. because they are still using old class names. If you are not using such extensions, you do not need to install the compatibility7 extension.
  • The upgrade wizard, which migrates css_styled_content/fluid_styled_content allows parallel installation of both extensions in the system, making it possible to smoothly migrate from the now deprecated css_styled_content to fluid_styled_content.
  • The extension form_legacy contains the old form content element. The complete form element was replaced by a new form builder in the TYPO3 backend. If you are currently using forms, you should install form_legacy - and think about migrating your forms to the new extension.
  • The extension rtehtmlarea contains the old rich text editor which was replaced by ckeditor. Before installing you should check whether the new editor is already fulfilling all your requirements. ckeditor is easier to configure and runs smoother.

Troubleshooting

The following sections contain hints to help you solve common problems. Note that you should also check the section "System Environment" in the Install Tool, in which TYPO3 will inform you about errors and warnings in your installation which might influence performance. Follow the advice given there to fix those issues. This helps to solve or prevent most issues.

During troubleshooting, in the "Configuration Presets" section of the Install Tool, under "Debug settings", you should select the "Debug" preset. This is especially helpful, if e.g. in the Frontend you only see a blank page. With debug settings activated, the PHP error message will be displayed, which will help you narrow down the problem.

Apache

There are some settings in the server setup, which might need adjustment.

Enable necessary Modules

TYPO3 relies on a number of Apache modules. Especially the modules mod_expires and mod_rewrite should be enabled in the Apache configuration. This can be done in the Apache configuration files, e.g. in httpd.conf, with these lines:

LoadModule expires_module modules/mod_expires.so
LoadModule rewrite_module modules/mod_rewrite.so

Adjust ThreadStackSize on Windows

If your server is running on Windows, the extension manager might not show up. Instead you might only see a blank screen in the right frame.

This problem is caused by the value of ThreadStackSize, which on Windows systems by default is way too low. To fix this, add the following lines at the end of httpd.conf:

<IfModule mpm_winnt_module>
  ThreadStackSize 8388608
</IfModule>

PHP

Install Tool

In the Install Tool the section "System environment" informs about missing PHP modules and problematic settings.

E.g. the PHP extensions openssl and fileinfo must be enabled. This can be done by adding (or uncommenting) the following lines in the [PHP] section in php.ini:

extension=fileinfo.so
extension=openssl.so

On a Windows-based server, these are the extension files:

extension=php_fileinfo.dll
extension=php_openssl.dll

PHP Caches, Extension Classes etc.

There are some situations which can cause what appear to be totally illogical problems after an upgrade:

  • If extensions override classes in which functions have changed. Solution: Try disabling all extensions and then enable them one by one until the error recurs.
  • If a PHP cache somehow fails to re-cache scripts: in particular, if a change happened to a parent class overridden by a child class which was not updated. Solution: Remove ALL cached PHP files (for PHP-Accelerator, remove /tmp/phpa_*) and restart Apache.

MySQL

Character Sets

Current versions of TYPO3 use UTF-8 encoding. You should make sure that MySQL uses UTF-8 as well. This is done most easily by checking that the new, empty database uses the character set UTF-8. In a database with content, all tables and those columns, which have a character set, must use UTF-8.

TYPO3-specific

Cached Files in typo3temp/

Generally you should know that TYPO3 generates temporary "cached" files and PHP scripts in typo3temp/Cache/. You can remove the whole typo3temp/Cache directory at any time; the directory structure and all the caches will be re-written on the next hit to the system.

A shortcut to remove these caches can be found in the Install Tool, under "Important Actions". This might be handy in case some of your cache files is damaged and your system is not running correctly. The Install Tool won't load any of these caches or any extension, so it should be safe to use regardless of the corrupt state of the Caches.

Amongst other caches, under typo3temp/Cache/Code/cache_core/ you find files like these:

-rw-rw----   1 www-data   www-data   61555  2014-03-26 16:28   ext_localconf_8b0519db6112697cceedb50296df89b0ce04ff70.php
-rw-rw----   1 www-data   www-data   81995  2014-03-26 16:28   ext_tables_c3638687920118a92ab652cbf23a9ca69d4a6469.php

These files simply contain all ext_tables.php and ext_localconf.php files of the installed extensions concatenated in the order they are loaded. Therefore including one of these files would be the same as including potentially hundred PHP- files and that saves some milliseconds for the system.

Concerning these files you have to consider the following:

  1. Making changes to these files does not make sense, because they can be removed and recreated from the "originals" at any time. You should instead change the "originals".
  2. If you make changes to the original ext_tables.php or ext_localconf.php files in your extensions, you will have to clear the cached files away for your changes to take effect.

Possible Problems with the cached Files

Changing the absolute path to TYPO3

If you change the path of the TYPO3 installation, you might get a lot of errors like "Failed opening ..." or "Unable to access ...". The problem is that absolute file paths are hard-coded inside the cached files.

Fix: Clean the cache using the Install Tool: Go to "Important Actions" and use the "Clear all caches" function. Then hit the page again.

Changing Image processing Settings

When you change the settings for Image Processing (in normal mode), you must take into account that old images may still be in the typo3temp/ folder and that they prevent new files from being generated! This is especially important to know, if you are trying to set up image processing for the very first time.

The problem is solved by clearing the files in the typo3temp/ folder. Also make sure to clear the database table "cache_pages".