TYPO3 Blog

How to install TYPO3 using composer (in less than 5 minutes)

During the last TYPO3 User Experience Week (T3UXW) it became apparent that some participants weren't aware of the benefits of a composer-based TYPO3 installation. Today I would like to use the opportunity to demonstrate the setup of a new TYPO3 installation with only a couple of commands, easing the way to TYPO3 as much as possible.

Prerequisites

This guide assumes that you have access to the shell of your system and that you have installed composer.
If you have not installed composer, yet, please click here and check how to install composer on your Operating System.

Compose your code

cd /path/to/your/htdocs/directory

Be aware that during the installation a subfolder called "web" will be created. Everything publicly accessible needs to be stored in that folder while confidential files, like configuration, must be stored outside of said "web" folder.
(Hint: If you want to change the name of the "web" folder, this is  very simple. I will get to that at a later point in this article.)

composer init

This starts the composer configuration generator. You will be asked a couple of informations, all of them could be edited later on.

  • Package name: A key to describe your project. E.g. "typo3inc/testcomposersetup".
  • Description: In this case I simply use: "This project is about to show how easy it is to create a composer based TYPO3 installation."
  • Author: The author name goes here.
  • Minimum Stability: Possible values are dev, alpha, beta, RC and stable.
  • Package Type: Project
  • License: Can be any type of string.
  • "Would you like to define your dependencies (require) interactively?": Yes
  • typo3/cms (as version constraint you could either enter "8" to stay on the LTS version or leave the field blank to always get the newest sprint release)
  • "Would you like to define your dev dependencies (require-dev) interactively?": No
  • "Do you confirm generation?": Yes

Now inspect the content of the directory, you'll find a file named composer.json.
Remember, I told you that it is possible to change the web folder name? Here is how it is done.
Add the following part to your composer.json file:

"extra": {
       "typo3/cms": {
           "web-dir": "web/public"
       }
}

The option “web-dir” allows us to define another path/name for the web folder, in this example the web folder name is changed to “web/public”. If you are on a case sensitive system, be sure to stick with upper and lower casing as you define here. 

Now let composer do its magic.

composer install

Depending on your coffee maker and your internet connection you might be able to go grab a quick cup of joe, but be quick about it, because even with cold caches it should not take longer than 2 minutes.
Now open your install tool in the browser and there you are. (Remember, the folder with your installation is the web folder. Configure your web server accordingly.)

More automation

I think we have about two minutes left so let's prepare the database connection.

composer require helhum/dotenv-connector

This composer package provides an easy way to store configuration outside of your web root.
Create a file called ".env" in the parent of your web folder and enter (and complete) the following lines:

TYPO3_INSTALL_DB_DRIVER=<your custom driver or omit this setting>
TYPO3_INSTALL_DB_HOST=<your host e.g. localhost>
TYPO3_INSTALL_DB_USER=<your db user for this project>
TYPO3_INSTALL_DB_PASSWORD=<the users password>
TYPO3_INSTALL_DB_PORT=<your custom port or omit this setting>
TYPO3_INSTALL_DB_DBNAME=<the db of your project>
TYPO3_INSTALL_DB_UNIX_SOCKET=<your custom socket or omit this setting>

When you go back to the install tool, most of the database configuration is already done.

Conclusion

Not only did we prepare a TYPO3 installation in less than 5 minutes, you also should have caught a glimpse of what would happen if you create the composer.json and a customized .env file to provision a hundred TYPO3 installations at once.

Jan Helke

About the Author

Jan Helke

Codegeneer, Hamburg, Germany
Jan worked with TYPO3 since version 3.8 up to the current master. By starting as TYPO3 developer in 2004 he took the step from hobby to profession. He believes that a professional, maintained CMS is of great value to all involved agencies and developers. In his spare time he likes to play boardgames, do Square Dance and draw maps.

More posts by Jan Helke

Comments

  • Anja Leichsenring

    Anja Leichsenring

    12. September 2017

    as for the question of the version to give for 'composer require typo3/cms': - Leaving the version blank will always give you the latest stable version. At the time of this writing this would be 8.7.6, and would end up in composer.json as ^8.7. - Providing a major version will give you the latest stable version of this branch, and also make for ^8.7. - Providing a minimum version like ^8.7 (as Peter mentioned) will of course give you that as well, but it is not necessary. Conclusion: Providing a major version is completely fine and sufficient for retrieving a dependency. It will also kept to the latest version as long as there will be some released. You must not worry on your own, and also you must not know what the current minor version of your required software is. Composer knows, that should fit the bill just fine.

  • Anja Leichsenring

    Anja Leichsenring

    12. September 2017

    I removed the spaces around the equal signs in the .env example. You guys are of course right, those must not be in the file. We apologize for this error.

  • Daniel Ruf

    Daniel Ruf

    11. September 2017

    I just wanted to mention that the example for the .env file still contains spaces around the equal signs.

  • Martin Bless

    Martin Bless

    06. June 2017

    Thank you very much. I'm just trying the .env file. To make it work I needed to remove the whitspace around the "equals" (=) sign. Otherwise PHP-FPM complained in the Apache2 errorlog: [:error] [pid 9392] [client 10.0.2.2:48153] FastCGI: server "/usr/lib/cgi-bin/php7-fcgi-t3dev8" stderr: PHP message: PHP Fatal error: Uncaught Symfony\\Component\\Dotenv\\Exception\\FormatException: Whitespace are not supported after the variable name in "/home/marble/htdocs/t3dev8/.env" at line 1.

  • Peter

    Peter

    11. April 2017

    Version constraint should be ^8.7 to stick with the current TYPO3 8.7 LTS release and not 8, correct?

  • Peter

    Peter

    11. April 2017

    Please add this information also to https://composer.typo3.org

  • Jo

    Jo

    10. April 2017

    Actually people were aware of the benefits, but not of the drawbacks due to an important missing piece of information. Since I was one of the people, who lost hours of time trying to fix development machines of participants based on composer, and you were one of the people who had to bear my outburst, I would like to say thank you for this article. It is the very first time that the "web" folder is explicitely mentioned, which is created silently under the hood during "composer install". While this does not change anything with a fresh install into an empty root directory, it is an unexpected and for most of the User Experience Week participants even undetected breaking change, when this folder is created within an existing and working installation just by executing "composer install". So people should be aware of the fact that this folder adds one path level to the whole "typo3conf" section, which will be changed to "web/typo3conf", while leaving the existing "typo3conf" folder as is. In case you upload changes to that former "typo3conf" directory i.e. via PHPstorm synchronization, nothing will happen. When you find that unexpected "web" folder on your machine later on and remove it, because it looks suspicious to you, the machine will be broken. So that particular information about the "web" folder and why and how it is created would be one of the essential things to tell people, who got problems with TYPO3 machines in composer mode. So I would like to see at least links to this article from a more prominent position than this blog. Thanks again and keep up the good work :-)

Write comment

Feedback