How to Automise Your TYPO3 Deployment (2020)

How to Automise Your TYPO3 Deployment (2020)

Are you looking for automatic & modern TYPO3 Deployment? Then, you are in the correct place. In this article, You will learn the step-by-step guide TYPO3 deploy with CI/CD approach for beginners to intermediate TYPO3 developers.

In the modern TYPO3 development era, Are you still developing and deploying your TYPO3 project with a tool like SFTP? Then, my friend, You should consider learning and implement TYPO3 deploy techniques. Trust me; your life will be much better, more comfortable with TYPO3 development, deployment, and maintenance.

Just imagine the situation, you are working on one TYPO3 project and completed many features, now you want to go live or staging servers for your customers - How’s that hectic?

But to save your time, with the most famous PHP deployer tool. As a PHP developer, you should be a product of such an excellent CI/CD deployment tool that built-in PHP language. It shows the limitless power of PHP.

With a Deployer, You just need to run one command to deploy everything automatically.

// Just run to deploy your TYPO3 website to the server
dep deploy

Isn't’ it cool, huh? Then, without waiting, Let’s get started to learn, explore, and implement modern TYPO3 deployment.

What is TYPO3 Deployer?

What is TYPO3 Deployer

PHP (Deployer) is a very convenient and fantastic tool for the deployment of any PHP based applications easily. Deployer is an open-source application, and it is available for free of cost. A portion of the known platforms it supports are MVC/CMS is, TYPO3, Laravel, CakePHP, Codeigniter, Drupal, and some more.

Why TYPO3 Deployer?

Deployer accompanies a simple set up procedure, and it requires minimal effort to learn. Anybody with some programming and coding ability can undoubtedly begin creating scripts with PHP Deployer. Aside from that, Deployer has a vast community network that serves a lot of the pre-prepared scripts to utilise contents (Deployer plans) to begin working with.
 

Features of TYPO3 Deployer

  • The simple setup process and a minimal learning curve
  • Ready to use recipes for most frameworks
  • Parallel execution without extensions
  • Did something go wrong? Rollback to the previous release
  • Agentless, it’s just SSH.
  • Zero downtime deployments

Classic vs Modern TYPO3 Deployment

Classic TYPO3 Deployment, It means, You are still working old-school ways to create the TYPO3 website at the local server and manually uploading your code/files through SFTP.

Modern TYPO3 Deployment means you improved your self with advanced concepts of CI (continuous integration) / CD (continuous deployment).

The TYPO3 Deployer works - To automatically deploy your TYPO3 website from GIT to SERVER.

How to Install and Configure TYPO3 Deployer?

You can install and configure a TYPO3 deploy in many ways at your application level (using PHP PHAR file) or a global scale level.

Good thing, PHP Deployer community also include “TYPO3” CMS as part of the core with providing ready-to-go TYPO3 deploy.

For the beginning, Let’s install and configure it globally with the below steps.

Pre-Requisites for TYPO3 Deployment Tool

  • PHP >= 7.3
  • Setup your TYPO3 site with GIT like Giteffortlesslab, Github, etc.
  • SSH Access of your Staging, Production, etc. server

Option 1. Download Deployer phar archive (recommended for Beginner)

To install Deployer as phar archive, run the following commands:

curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep

Option 2. Source Composer Deployer installation

// To install Deployer source version with Composer, run the command:
composer require deployer/deployer --dev

// You can also install it globally:
composer global require deployer/deployer

Option 3. Distribution Composer Deployer Installation

To install the Deployer distribution version with Composer, run the command:

composer require deployer/dist --dev

// Let’s have quick test-drive
dep --version

How to Deploy TYPO3?

Now without much waiting, Let’s have a practical example with a step-by-step guide of TYPO3 Deploy as below.

Step 1. Configure TYPO3 Servers and Stages

At your root of the project, Create .hosts.yaml file with below settings.

// .hosts.yaml

// Configure your TYPO3 staging site
staging.typo3site.com:
  host: staging.typo3site.com
  stage: staging
  branch: staging
  user: username
  identityFile: ~
  deploy_path: /var/www/yourpath

// Configure your TYPO3 production site
typo3site.com:
  host: typo3site.com
  stage: production
  branch: master
  user: username
  identityFile: ~
  deploy_path: /var/www/yourpath

Step 2. Prepare TYPO3 Deploy

At your root folder of the project, Create deploy.php file as below which is a working example of the TYPO3 deployer. It’s effortless and easy to understand each step.

<?php

namespace Deployer;

# Call default recipe
require 'recipe/common.php';

# Project name
set('application', 'your-typo3-site');

# Define Git-Repository
set('repository', '[email protected]:yourcompany/yourtypo3project.git');

# [Optional] Allocate tty for git clone. The default value is false.
set('git_tty', true);

# Set maximum releases backup
set('keep_releases', 5);

# To solve this issue: Can't detect http user name. Please set up the `http_user` config parameter.
# set('http_user', 'www-data');
# set('writable_mode', 'chmod');
# set('use_relative_symlink', '0');

# Set Server
inventory('.hosts.yaml');

# DocumentRoot / WebRoot for the TYPO3 installation
set('typo3_webroot', 'public');

# Shared directories
set('shared_dirs', [
   '{{typo3_webroot}}/fileadmin',
   '{{typo3_webroot}}/typo3temp',
   '{{typo3_webroot}}/uploads',
]);

# Shared files
set('shared_files', [
   '{{typo3_webroot}}/.htaccess'
]);

# Writeable directories
set('writable_dirs', [
   'config',
   'var',
   '{{typo3_webroot}}/fileadmin',
   '{{typo3_webroot}}/typo3temp',
   '{{typo3_webroot}}/typo3conf',
   '{{typo3_webroot}}/uploads'
]);

# Main TYPO3 task
task('deploy', [
   'deploy:info',
   'deploy:prepare',
   'deploy:lock',
   'deploy:release',
   'deploy:update_code',
   'deploy:shared',
   'deploy:vendors',
   'deploy:writable',
   'deploy:symlink',
   'deploy:unlock',
   'cleanup',
])->desc('Deploy your project');
after('deploy', 'success');

# [Optional] If the deployment fails automatically unlock.
after('deploy:failed', 'deploy:unlock');

Note:
Above example, TYPO3 deployment code is well-tested with TYPO3 v10 and Composer-based TYPO3 Installation. Please do require changes to make it compatible with your other kind of TYPO3 installation.

Step 4. That’s it, Now let’s Deploy TYPO3!

// Run this command as test-drive deployment to your TYPO3 staging site
dep deploy staging

Aha, Are you getting SSH authentication errors?

No problem! One thing you need to understand, Deployer is a bridge to connect your Git repository and your Server. Let’s configure SSH authentication for your Git and Server.

Step 1. Generate SSH Key at your local server (if you don’t have)

ssh-keygen

Step 2. Let’s put your SSH keys to the staging and production server

ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]

Step 3. Configure SSH key to Git

For example, in Gitlab, go to https://gitlab.com/profile/keys and add your staging and production server’s public key.

Ready-to-use TYPO3 Deployment Packages

The good thing is that some people are trying to develop and maintain TYPO3 deployer packages as below. You should try and take advantage of such ready-made TYPO3 deployment packages.

#1 TYPO3 Deployer Toolkit (from Oliver Hader)

Oliver Hader - The head of the TYPO3 Security team initiated the TYPO3 deployer toolkit with a wide range of options available for automise TYPO3 deploy.

// Install TYPO3 deployer toolkit
composer req --dev oliver-hader/typo3-deployer

// Configure deploy.php & .host.yml

// Deploy your TYPO3 project
vendor/bin/dep deploy production

#2 TYPO3 Deployer Information (by Thomas Löffler)

The TYPO3.org man - Thomas Löffler developed a cool TYPO3 extension to Show information about the last deployment in the system information toolbar - in TYPO3 backend.

// Install EXT:deployer_information
composer req spooner/deployer-information

// How to configure your deployment
// You don't need to do anything. The extension looks for the default folder and files of a release.

#3 TYPO3 Deployer Recipe (from Helmut Hummel)

Helmut Hummel created a recipe for TYPO3 deploy. There is no documentation available, But as just like other projects of Helmut, it should be awesome, Try it :)

Deployer Extended for TYPO3 (from Sourcebroker)

Sourcebroker, One of the very active guys on TYPO3 deployer, they have created an excellent solution for the TYPO3 deployer for code, database, media-assets, etc. I have given a quick try, and it works fantastic.

This package serves a deploy task to deploy TYPO3 CMS with deployer (deployer.org). 

// Installation deployer-extended-typo3
composer require sourcebroker/deployer-extended-typo3

// Put below code at beginning of your deploy.php
require_once(__DIR__ . '/vendor/sourcebroker/deployer-loader/autoload.php');
new \SourceBroker\DeployerExtendedTypo3\Loader();
// Run deploy
dep deploy beta

Working Example of TYPO3 Deployment

<?php

namespace Deployer;

require_once(__DIR__ . '/vendor/sourcebroker/deployer-loader/autoload.php');
new \SourceBroker\DeployerExtendedTypo3\Loader();

set('repository', '[email protected]:sourcebrokergit/t3base10.git');
set('bin/php', '/home/www/t3base10-public/.bin/php');
set('web_path', 'public/');

host('live')
    ->hostname('vm-dev.example.com')
    ->user('deploy')
    ->set('branch', 'master')
    ->set('public_urls', ['https://live-t3base10.example.com'])
    ->set('deploy_path', '/home/www/t3base10-public/live');

host('beta')
    ->hostname('vm-dev.example.com')
    ->user('deploy')
    ->set('branch', 'master')
    ->set('public_urls', ['https://beta-t3base10.example.com'])
    ->set('deploy_path', '/home/www/t3base10-public/beta');

host('local')
    ->hostname('local')
    ->set('deploy_path', getcwd())
    ->set('vhost_nocurrent', true)
    ->set('public_urls', ['https://t3base10.local.site']);

Helpful Tips & Tricks for TYPO3 Deploy

#1 How to Debug TYPO3 Deployer?

Whenever you get stuck with some random unknown error, then you should try dig-n-depth using the deployer's variance debugging ways while running your deployment.

// provides default installation view with the least information
dep deploy -v

// provides some more details as compared with the default mode
dep deploy -vv

// provides a detailed view of the installation output
dep deploy -vvv

#2 How to TYPO3 Deploy a Particular Stage?

As we have seen above TYPO3 deploy example, you can configure multiple deployments with staging, production, etc.,

// To deploy to the TYPO3 staging server

dep deploy stage

// To deploy to the TYPO3 production server

dep deploy production

#3 Is there a way to rollback TYPO3 Deployment?

Yeah, the Deployer tool is incredible; you can quickly deploy it with a simple rollback command.

// Rollback your last run TYPO3 deploy
dep rollback

#4 Release Management for TYPO3 Deploy

The deployer created several releases folder using the keep_releases task.

// Keep maxim five release and other will old-releases keep deleted
set('keep_releases', 5);

// To clean-up all old releases
dep cleanup

#5 Available Deployer Recipes

PHP Deployers have a great community who continually prepare recipes for the deployment.

// Install all Deployer Recipes

composer require deployer/recipes --dev

// Include particular recipes in your Deploy.php

require 'recipe/typo3.php';

#6 Zero Downtime TYPO3 Deployment

One of my favourite features is zero downtime TYPO3 deploy. Depending on your size of the TYPO3 website, It may require to deploy code and assets from Git to your server.

A simple solution is, Point your domain to /current folder.

#7 Keep up-to-date Deployer

Deployer community continuously releases new versions, Keep exploring and stay update-to-date deployer with simple below commands.

// To update the minor version of the Deployer run,
dep self-update

// To update the Deployer to major release version run,
dep self-update --upgrade

#8 Advanced Automize = Deployer + Git Releases Management

I suggest you integrate the deployer to Git release manager to implement a CI/CD approach fully. Example, If you are using Gitlab;

Step 1. Prepare .gitlab-ci.yml with configuring PHP deployer installation, configuration, etc.

Step 2. Also, insert dep deploy command setup into Gitlab-CI file.

Step 3. So, Whenever you release the tag, it will automatically deploy your TYPO3 site to the server.

In future, I’ll surely write down such step-by-step guide separate blog, stay tuned by subscribing our TYPO3 Blog.

Conclusion

Thanks for reading the article.

I hope you liked and learned the deployment way of TYPO3 + Deployer. Here are some conclusion points.

  • Understand the underlying architecture of the Deployer tool, eg.; It’s deployed from GIT to SERVER.
  • Install and configure to start using the "dep" command.
  • Prepare your first TYPO3 deploy project to test-drive at your staging server (and keep practice).
  • Learn the structure of deploy.php so in the future, and you can adapt it according to your needs.
  • I highly recommend giving a try to ready-to-use TYPO3 deploy packages.

Are you facing any issues while installing, configuring, and testing your TYPO3 deployer project? I’ll be happy to answer any questions in the comment box.

Have a Happy TYPO3 Deployment!

Post Comment

Your email address will not be published. Required fields are marked *

×

Name is required!

Enter valid name

Valid email is required!

Enter valid email address

Comment is required!

Google Captcha Is Required!

Comments :

  • Adelar Kampf August 7, 2020 At 1:15 pm
    I always loved your articles Sanjay. Indeed this is a good automated deployment article. Thanks so much for putting all this together. Great tips and tools mentioned.
  • Emilie Lasker August 7, 2020 At 1:11 pm
    Great article on the preparation for automated deployments, these are often overlooked steps and can make or break the TYPO3 deployment set up. Thanks for sharing and looking forward to more of the blogs!
Trending: What Is TYPO3 Headless CMS?

Trending: What Is TYPO3 Headless CMS?

“TYPO3 Headless CMS” word started to buzz! The future of CMS is quickly moving away from Traditional to Headless CMS. Are you…

Interview with Thomas Löffler: Building Better TYPO3 Eco-system

Welcome to the TYPO3 Interview Series - 3! We are excited to launch the TYPO3 initiative for business executives, marketers,…

Interview with Jochen Weiland: Building Better TYPO3 Eco-system

Welcome to the TYPO3 Interview Series - 2! We are excited to launch the TYPO3 initiative for business executives, marketers,…

Stay up to date with our recent TYPO3 Blogs, news, & updates