Installation and Upgrade Guide

Transcription

1 Installation and Upgrade Guide Release 7 Documentation Team :35

2

3 CONTENTS 1 Introduction About this document What s new Credits Feedback Quick Installation Get and Unpack the TYPO3 Package The Install Tool In-Depth Installation System Requirements Which Package and which File Format? The Package in Detail The Install Tool The Distributions Translating the Backend Upgrade Links Steps Upgrade from LTS to LTS Introduction Preparation in 4.x LTS Upgrade Process From DAM to FAL Troubleshooting Apache PHP MySQL TYPO3-specific i

4 ii

5 CONTENTS Previous Key doc_guide_install Version 7 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 Author Documentation Team documentation@typo3.org License Open Content License available from Rendered :35 The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from 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 CONTENTS 1

6 Installation and Upgrade Guide, Release 7 2 inspiring people to share.

7 CHAPTER ONE INTRODUCTION 1.1 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. 1.2 What s new Updated the manual for TYPO3 CMS version 6.2 and added a chapter for upgrading from 4.5 LTS to 6.2 LTS. 1.3 Credits This manual was originally written by Kasper Skårhøj and is now kept up to date by the documentation team. 1.4 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 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: 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 ( 3

8 Installation and Upgrade Guide, Release 7 4 inspiring people to share.

9 CHAPTER TWO QUICK INSTALLATION The following instructions assume you are able to create symlinks on the target machine. 2.1 Get and Unpack the TYPO3 Package Installing on a Unix server 1. Get the Source Package from 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 File 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/6.2 -O typo3_src-6.2.x.tar.gz 2. Unpack the typo3_src-6.2.x.tar.gz file on your web server: /var/www/site/$ tar xzf typo3_src-6.2.x.tar.gz 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-6.2.x typo3_src ln -s typo3_src/index.php index.php ln -s typo3_src/typo3 typo3 4. 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-6.2.x/ htdocs/typo3_src ->../typo3_src-6.2.x/ htdocs/typo3 -> typo3_src/typo3/ htdocs/index.php -> typo3_src/index.php htdocs/.htaccess The advantage of this setup is that all files from the TYPO3 Source package are kept together in the typo3_src-6.2.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. 5

10 Installation and Upgrade Guide, Release 7 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 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.tar.gz file. (If you are not sure which package you should choose, read the section Which Package and which File 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-6.2.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-6.2.x/ htdocs/typo3_src ->../typo3_src-6.2.x/ htdocs/typo3 -> typo3_src/typo3/ htdocs/index.php -> typo3_src/index.php htdocs/.htaccess 2.2 The Install Tool 1. Hit the start page of your freshly created site with your browser and the Install Tool will open in the so called mode. It will guide you through the steps for installing TYPO3. (The Install Tool is located in typo3/install in your installation, e.g This is what you should see: 3. 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. 6 inspiring people to share.

11 Chapter 2. Quick Installation 4. Enter your database credentials. Enter MySQL username and password. In most cases the database host is localhost. 5. Create a new database for TYPO3 or use an existing empty database. 6. 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). 7. In the last step you can choose whether you want to download and install an existing distribution after your first Backend login. If you want to start with an empty installation, untick this checkbox. 8. 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 The Install Tool 7

12 Installation and Upgrade Guide, Release 7 8 inspiring people to share.

13 CHAPTER THREE IN-DEPTH INSTALLATION 3.1 System Requirements TYPO3 requires a web server, PHP and a database system. TYPO3 requires a web server which can run PHP (e.g. Apache or IIS). TYPO3 6.2 requires at least PHP TYPO3 can be used with a great many database systems. If you use MySQL, you will need to implement at least MySQL 5.1. If you use the 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. 3.2 Which Package and which File Format? Which Package to use There is only one TYPO3 Package, called TYPO3 Source, with which you can install an empty instance of TYPO3. Once the main installation process is complete, you will be asked whether you want to load additional Distributions to kick start an out-of-the-box working environment. An overview of all available packages and versions (which also contains older supported releases) can be found at 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. 3.3 The Package in Detail TYPO3 Folders and Files The following files and folders are part of the TYPO3 Source package. 9

14 Installation and Upgrade Guide, Release 7 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 TYPO 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 templates, user uploads, external scripts and images 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. 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? 3.4 The Install Tool The Install Tool provides tools to help you with the maintainance 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. 10 inspiring people to share.

15 Chapter 3. In-Depth Installation First go to your site and enter the install tool ( 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. 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 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 Character set conversion settings allows you to select the program which should be used for character set conversions The Install Tool 11

16 Installation and Upgrade Guide, Release 7 The section Development / Production settings allows you to set an application context, in which TYPO3 should be running. E.g. if set to Development, all kinds of error reporting, debugging and deprecation logging will be activated. If set to Production, 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. Finally the preset Extbase object cache allows you to choose the kind of caching system for Extbase to use 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 You don t need the upgrade wizard while installing TYPO3. This function will be explained in a later chapter about upgrading TYPO 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 TYPO 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. 3.5 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 12 inspiring people to share.

17 Chapter 3. In-Depth Installation and content elements, as well as automatically handling the installation and activation of assistant 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.) Amongst non-core options, the following Core Distributions are available: Introduction Package The Introduction Package is a complete demo website. It it based on a responsive design and contains a lot of default content for testing and learning. Try this one if you are new to TYPO Government Package The Government Package is a demo website. It contains a collection of best practices to enhance the level of web accessibility. The contents are rendered in HTML5 based on the famous HTML5Boilerplate. Navigation and content elements are defined to be accessible for screen readers and keyboard navigation. HTML5 semantics are used to add more meaning and structure to the appropriate elements. Since web accessibility guidelines are strict on contrast ratio and readability, an alternative view has been integrated, which allows you to use an alternative, contrast-enhanced stylesheet Installing Distributions For testing and learning we recommend that you use the Introduction Package. If accurately adhering to web standards is especially important to you (e.g. as required for government bodies in the European Union), you might want to try the Government Package. Just choose the Distribution you d like to use and hit Install. Clicking on Note: The installation process of a Distribution can take a long time. On a current laptop I had to wait around 100 minutes for the introduction package to finish installing. Do not abort this process - be patient! If you want to build your website from scratch, just go ahead without using a Distribution. You can then start with a completely empty installation of TYPO 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 Translating the Backend 13

18 Installation and Upgrade Guide, Release 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. 14 inspiring people to share.

19 CHAPTER FOUR 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 included ChangeLog to see if any features affect the way your site works. (Look for lines prepended with!!! - those are the really important ones!) 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! 4.1 Links Upgrade walkthroughs by TYPO3 users Upgrade guide by jweiland.net (in German) Upgrading 4.5->6.2 with OS X and Linux (Stack Overflow) 4.2 Steps Basically these are the steps to be done to update your TYPO3 site: 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 Install the new Source Upgrade the distributed source files to the new version. You can do this either using the Core updater or manually. 15

20 Installation and Upgrade Guide, Release 7 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 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. What s the next step? In case you did a minor update, e.g. from TYPO to 6.2.3, 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 6.1 to 6.2, 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/. 16 inspiring people to share.

21 Chapter 4. Upgrade 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 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.) 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, 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 4.2. Steps 17

22 Installation and Upgrade Guide, Release 7 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. The last upgrade wizard Update database schema: Modify tables and fields finally changes definitions of existing tables and columns as needed. 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. 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. 18 inspiring people to share.

23 Chapter 4. Upgrade 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: When you then click Compare current database with specification again and you only see the message 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 : 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 Steps 19

24 Installation and Upgrade Guide, Release Check the ChangeLog and NEWS.md Look through the ChangeLog and the NEWS.md files in your extracted TYPO3 package. They contain information about new functions you might need or be interested in. Especially pay attention to lines starting with!!!. They are especially important, because they are about changes that may affect the operation of some websites Update Extensions 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.) 20 inspiring people to share.

25 CHAPTER FIVE UPGRADE FROM LTS TO LTS This chapter provides in depth information about how to update from TYPO3 4.5 LTS to the TYPO3 CMS 6.2 LTS version. It will explain: What has changed How to plan your upgrade / migration What caveats to expect and where to get help How to proceed with the upgrade 5.1 Introduction This chapter will give you a historical perspective on what happened since TYPO3 4.5, why things changed the way they did, and what to expect from the migration from 4.5 to Deprecation Strategy With TYPO3 CMS up until version 4.5, users were able to upgrade from one version to the next one with very little effort. By upgrading, users gained new functionality whilst ensuring that old technology would usually continue to work. This is called backwards compatibility. TYPO3 CMS users are used to a high level of backwards compatibility. With backwards compatibility come downsides: the code base gets larger and larger; the old code still needs to be maintained (security and testing when considering new or changed features and interfaces); users (developers, integrators) adapt more slowly to newer technologies and best practices that emerge with newer versions. This is why several years ago specifially, during development of version 4.3 in 2009 the core team agreed to introduce a consistent deprecation policy. TYPO3 CMS deprecation policy If a method or API in the Core is replaced by a new one and is no longer used by the Core itself, it can be marked as deprecated and can be removed two releases later. Deprecated API methods are marked in the PHP code annotation. At the same time the deprecation log was introduced in order for users to be able to identify potential old methods still being used by an existing installation. At that time (2009) there were already many methods marked as deprecated: some as early as TYPO 3.5. Until version 4.5 LTS (2011), the core team didn t practice the removal part of the strategy consistently. With the release of 4.5 LTS, it was decided to retain all methods for the last time which had been deprecated sufficiently long enough that they could have been removed already. The core team started removing them in 4.6 (and later), which is why TYPO3 4.6 is subtitled Rebase. Four years later (with the releases 4.6, 4.7, 6.0, 6.1 and 6.2), lots of methods are finally really gone. Some users doing the first upgrade after 4.5 LTS to 6.2 LTS may therefore face some major issues with their sites. 21

26 Installation and Upgrade Guide, Release Smooth Migration To help and guide administrators, integrators and developers for the challenges posed by the mentioned changes in the Core, a Smooth Migration project was created for TYPO This has the goal of smoothing the upgrade process as much as possible. It is aiming for the following goals. 1. Migration shall be possible in all areas. 2. Migration should be plannable and is quotable. 3. Migration should work as planned. The following chapters explain how you can plan, prepare and execute the migration from TYPO3 CMS 4.5 (or 4.7) to the latest 6.2 LTS release. 5.2 Preparation in 4.x Preconditions 1. TYPO3 Version Make sure your installation is running at least TYPO3 4.5 LTS. The TYPO3 6.2 upgrade process is possible from any version from 4.5 (i.e. 4.6, 4.7, 6.0 or 6.1). If you are running a lower version of TYPO3, please upgrade to 4.5 first. 2. New system requirements Make sure the new environment fulfills the necessary system requirements: especially PHP. (PHP 5.2 is no longer supported.) For details on the specific requirements, check the INSTALL.md file bundled with the TYPO3 Source package Preparation steps In the original 4.x TYPO3 installation, do the following: Extensions 1. Upgrade the extensions in use to the latest possible version that is available for your old installation. Check if any extension that you are using is not compatible with TYPO Uninstall extensions that you are not using, in order to clean up your installation and remove deprecated and potentially dangerous code. 3. Physically remove unnecessary extensions from the typo3conf/ext directory. Note: There are many extensions which provide compatibility with both TYPO 4.5 and 6.2, which are able to run perfectly fine in both TYPO3 releases. Reference Index Go to the Admin Tools > DB check module and use the Manage Reference Index function. Click on Update Reference Index to update the index in sys_refindex. This is especially important for later migrating references to files in the 6.2 FAL Upgrade Wizard. 22 inspiring people to share.

27 Chapter 5. Upgrade from LTS to LTS Compatibility Check Install the extension smoothmigration in your old installation. This extension provides a module in the Backend that is able to analyze your current installation in particular the installed extensions and give you hints on compatibility problems. The following checks will be carried out, with more to come as the extension will be updated regularly. Calls to deprecated and removed static methods: Some of these can be migrated automatically! Calls to deprecated Fluid view helpers Calls to PHP mysql_* methods (removed since PHP 5.5) Usages of removed constants (like PATH_t3lib, etc) Usages of require_once calls to core files that were moved or renamed. Simply remove the require_once call in your extensions and use the necessary classes. TYPO3 will take care of loading these namespaced classes by means of the auto-loader. This can be automatically migrated by this extension! Usages of XCLASS: The XCLASS concept was removed in TYPO3 6.x. There is now is a new method for registering replacement classes instead. Calls to DAM classes or methods, since DAM no longer works in TYPO Use FAL instead and adapt your extensions to using the new technology. Usage of a UTF-8 database. In the TYPO3 4.5 database, character sets other than UTF-8 were deprecated but could still be used. This is no longer possible in TYPO3 6.2, so this check will make sure you are using UTF-8 already in your database. The smoothmigration extension provides an automatic migration routine for this issue. 5.3 LTS Upgrade Process When the preparations are complete, the upgrade process is the same as before for minor level releases. (E.g. 6.1 to 6.2.) You can skip intermediate minor versions, so there is no need to do an intermediate upgrade to upgrade from 4.5 (or 4.7) to 6.2. Attention: You need to have upgraded to at least TYPO3 4.5 in order to upgrade to 6.2! Several things will be done automatically when you run the Install Tool of the new version for the first time. Some actions will even happen before the Install Tool opens. So don t forget to make a backup! The file:typo3conf/localconf.php will be adapted to the new 6.x style of configuration and saved as LocalConfiguration.php. Information about installed extensions will be moved to PackageStates.php file. The saltedpasswords extension will be installed and activated if it was not previously used. 1. Make sure you have gone through Preparation in 4.x. 2. Update the typo3_src symlink to point to the new release core. 3. Open the Install Tool in the browser. 4. Use the System Environment module to see if your system fullfills all required preconditions. 5. Use the Important Actions, item Check for broken Extensions. If there are extensions that might break your current installation (i.e. calling removed methods in their ext_localconf.php or ext_table.php), you must remove them until they are updated. 6. Use the Upgrade Wizard as usual to migrate your installation LTS Upgrade Process 23

28 Installation and Upgrade Guide, Release After the upgrade If you have not used DAM before and were just using regular files with TYPO3 Content Elements, the Upgrade Wizards will have converted your structure to FAL and you are all set and ready. If you were working with DAM (Digital Asset Management) in TYPO3 4.5 or 4.7, you will want to migrate your data to the core FAL (File Abstraction Layer). DAM and its related extensions no longer work with TYPO3 CMS 6.x. For this, read on in the next chapter. In TYPO3 CMS 4.5 languages could be defined by setting config.language = xy in TypoScript and having according labels in <languagekey index="xy" type="array"> in language files. In TYPO3 CMS 6.2 by default this is possible only for those language keys that have been defined in typo3/sysext/core/classes/localization/locales.php. If you want to use a language without a definition there (e.g. en_us), you have to add it on your own as described here: Custom languages. 5.4 From DAM to FAL If you have been working with DAM (Digital Asset Management) in TYPO3 4.5 or 4.7, you will want to migrate your data to the core FAL (File Abstraction Layer). DAM and its related extensions no longer work with TYPO3 CMS 6.x. Install the extension dam_falmigration. Read its documentation to learn about its capabilities and usage. 24 inspiring people to share.

29 CHAPTER SIX 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. 6.1 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 </IfModule> 6.2 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: 25

30 Installation and Upgrade Guide, Release 7 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. 6.3 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 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 www-data www-data :28 ext_localconf_8b0519db cceedb -rw-rw www-data www-data :28 ext_tables_c a92ab652cb 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. 26 inspiring people to share.

31 Chapter 6. Troubleshooting 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 TYPO3-specific 27