How to avoid some traps while migrating to Typo3 6.2 LTS

Some may know that we use Typo3 for editing the fodina-Pages - combined with the real-url extension, the crawler extension, and some self written sripts. Our idea is that we only want to push the pure html pages and embedded pictures to our web hoster, not the Typo3 system itself. So, we develop our content inside of a locally running Typo3 instance, crawl all elements into a local web directory and finally upload this directory into our web space.

For a long time we used Typo3 release 4.5 on Ubuntu 12.04 - the LTS versions. But this summer, we had to update our computers to Ubuntu 14.04 and to Typo3 6.2 as the next LTS releases. Unfortunately, the typo3 migration did not run as smoothly as we expected. But we find solutions. Often by using the web, sometimes by trying different options. So, it might be a good idea to share our experiences.

  • Login into the backend of your running Typo3 4.5 instance and follow the preparation steps described by the official Typo3 LTS to LTS Migration Tutorial:

    • Upgrade the 4.5 extensions you really use and erase the other
    • Call the DB check and update your reference indexes

  • Dump your mysql Typo3 4.5 instance database into a flat file using the command 'mysqldump -u root -p YOURDATABASE > YOURDATABASE-file.dump
  • Copy your web (root) typo3 directory TP3WEBROOT, which contains all the typo3 stuff like the directory 'fileadmin' and the links to the typo3 sources, into the http document root directory of a new computer (place) hosting a Typo3 6.2 instance.
  • On the new instance, modify the owner and the status of the copied directory and those of all of its sub-directories so, that your web-server user (www-data) is allowed to write / to modify the files - for example by the commands 'chown -R YOURUSER.YOURWEBSERVERGROUP TP3WEBROOT' and 'chmod -R g+w TP3WEBROOT'
  • By using myPhpAdmin, generate a new empty mysql database. Caution:

    • Assure, that you are using collation 'utf8_general_ci'.
    • Assure that the empty databse is named like the old 4.5-database.

  • Replace all 'utf8_unicode_ci' specification in your mysql database file by 'utf8_general_ci' - for example by using the vi and the command ':1,$ s/utf8_unicode_ci/utf8_general_ci/g'

    • Explanation: Later on you will use the Typo3 upgrade wizard which will reorganize your database. If you do not replace the ut8-collation-string, you might get the message "Update Failed!" because "Database query failed. Error was: Illegal mix of collations (utf8_general_ci,IMPLICIT) and (utf8_unicode_ci,IMPLICIT) for operation '<>'". We did not find any other solution than the replacing the utf8-unciode-collation by the utf8-general-collation.

  • Import the modified database dump into mysql by using the shell command 'mysql -u root p YOURDATABASE < YOURDATABASE-file.dump
  • In typo3conf/localconfiguration.php modify the password of the database user - if necessary
  • Replace the existing 'typo3_src' link by a link to the installed typo3 6.2 instance
  • Call the TP3 install tool by opening 'http://localhost/TP3WEBROOT/install/index.php' in your browser (probably you have to insert a flag file by using ' touch typo3conf/ENABLE_INSTALL_TOOL'):

    • In 'All configuration/TYPO3_CONF_VAR[SYS]' insert

      • 'SET NAMES uft8 COLLATE utf8_general_ci;' in [SYS][setDBinit]
      • 'en_US.utf8' (or any other appropriate value) in [SYS][systemLocale]

    • In 'Folder structure' let the folder structure be fixed by the system
    • In 'Upgrade Wizard' follow all required actions.

  • Caution:

    • Completely empty the typo3temp directory!
    • In the file 'typo3conf/ext/crawler/class.tx_crawler_lib.php'  disable the 'require_once-commands in line 30 until 33 (by commenting them out)

  • Login into the backend of your typo3 instance and open

    • Call the LTS-LTS Smooth Migration extension and respect its recommendations
    • Open the extension manager

      • replace your google-site-map-extension by dd_googlesitemap
      • Disable and erase LTS-LTS-smooth-migration
      • Open the realurl-configuration, enable the automatic configuration, toggle the value from serialized to PHP conf

    • Open the Web/Info/Root dialog, use 'ReaUrl Management', set depth to infinite and delete all entries
    • Save all values. delete the file 'typoconf/realurl_autoconf.php', open the frontend of your Typo3-instance - which should rewrite the file 'typoconf/realurl_autoconf.php' in an editable format. Rename the rewritten file 'typoconf/realurl_autoconf.php' to 'typoconf/realurl_conf.php'
    • Transfer all real url values from 'typo3con/AdditionalConfiguration.php' into the generated file 'typoconf/realurl_conf.php'
    • Open the extension manager, open the realurl-configuration, disbale the automatic configuration, assure, that 'path to the configuration file' maps the name of the newly generation configuration file

  • Caution: By using phpMyAdmin, trunc (but do not delete) the tables tx_realurl_chashcache, tx_realurl_errorlog, tx_reaurl_pathcache, tx_realurl_urldecodecache, tx_realurl_urlencodecache

    • Explanation: while migrating from 4.5 to 6.2, the database has already been refilled with realurl values without using the old and good configuration values. So, you should evoke a complete rebuild of all realurl evoked files and paths - with can not be done by the typo3 flush operations.

  • Caution: Insert 'tx_ddgooglesitemap.forceStartPid  = 1' into the setup part of your root template for enbaling the dd_googlesitemap-extension to find all pages.

    • Explanation: There are listed some different commands in the web. In our environment, this version was the only one which had an effect.

  • Bingo! Happy coding.