blueways deployer recipes

2.4.3 2024-05-10 08:09 UTC


This repository contains third party recipes that are build on top of sourcebroker/deployer-extended-typo3. This package sets default deployer values for a common TYPO3 base extension installation.

This Readme contains examples for configuring a TYPO3 base extension for easy deployment.

1. Install

composer require blueways/deployer-recipes

2. Adjust composer.json

You have to add some lines to your `composer.json` in order to read the Conf vars on the fly and add the symlink to the extension on every deploy.

   "extra": {
      "helhum/dotenv-connector": {
         "env-file": ".env",
         "adapter": "Helhum\\DotEnvConnector\\Adapter\\SymfonyDotEnv"
   "scripts": {
      "typo3-cms-scripts": [
         "ln -sfn ../../../ public/typo3conf/ext/bw_myext"
      "post-autoload-dump": [

3. Create deploy.php

Create a `deploy.php` in your project root. This is a simple configuration file for deploying to Mittwald hosts:


namespace Deployer;

require_once(__DIR__ . '/vendor/blueways/deployer-recipes/autoload.php');

set('repository', '');

    ->set('labels', ['stage' => 'testing'])
    ->set('branch', 'master')
    ->set('public_urls', [''])
    ->set('http_user', 'p590044')
    ->set('writable_mode', 'chmod')
    ->set('bin/composer', '/usr/local/bin/composer')
    ->set('bin/php', '/usr/local/bin/php')
    ->set('deploy_path', '/home/www/p590044/html/typo3-staging');

    ->set('deploy_path', getcwd());

4. Create AdditinalConfiguration.php

Add this file to public/typo3conf/ in order to parse TYPO3_CONF_VARs from environment variables.

5. Create .env

Put this .env file in your project root. It contains typical ddev settings, that would have been set through AdditionalConfiguration.php. These settings override the production settings of TYPO3.

6. Add files to git

Files to put in git:


Make sure that these files are not matched by your .gitignore. To add files that are excluded (like the ones inside the public directory), you can use the following command:

git add -f public/typo3conf/LocalConfiguration.php

6. (Optional) Configure your deployer command

Make sure to run the `depcommand from within the ddev container, e.g. add an alias to your~/.bashrcor~/.zshrc`:

alias dep="ddev exec vendor/bin/dep"

7. Prepare the host machine

Get ready to enter database credentials and configure the domain.

To create the folder structure and configuration on the remote host, run:

dep deploy:prepare:typo3 staging

Follow the wizard. If there are errors (e.g. missing software on host), fix the problems and re-run the command.

Now change the path of the domain (the ones configured in `public_urls`) to the working directory. The path is printed by the wizard. Activate SSL.

8. Deploy

Now you can create your first deployment with

dep deploy-fast staging

9. Import database or start fresh

You're basically done. Now you can decide whether you want to import your existing local database:

dep db:push staging

Or start from scratch by adding an admin user:

dep config:createadmin staging

10. Configure remote instance

If you configure the remote TYPO3 installation via Install Tool, make sure to add the changes to the git repository. To download the changes made to the LocalConfiguration.php, you can use the following command:

dep config:pull staging

If any of these changes break your local installation, just override the setting in your local .env file.


This package sets default values for various settings.

file_backup_packagesfileadmin, uploads (excluding _processed_ and _temp_)


  • db:backup:rsync
  • file:backup:rsync
  • config:pull
  • slack:notify
  • deploy:prepare:typo3
  • deploy-fast
  • file:backup


Rsync database backups to remote host.


Rsync file backups to remote host

SettingDefault value


Download the LocalConfiguration.php from remote instance to local instance


Notify slack channel on production deployment.

Contains multiple slack recipes in order to get rid of the abandoned repo (could change in the future). To add a webhook to your slack channel, visit this page and click on "Add to Slack".


Configures the host machine for the deployment of a TYPO3 base extension:

  • Can add your SSH key to remote machine
  • Checks for software dependencies
  • Add rsa fingerprint of git repository
  • Checks for correct repository access
  • Interactively create remote .env file with database credentials
  • Creates needed folder structure for domain configuration


Unfortunately this package has to override the deploy-fast task of sourcebroker/deployer-extended-typo3. This is done to change the order of commands in order to prevent an exception during initial deployment.

Hopefully, this will change in the future. The discussion can be found here.


This recipe overrides the file:backup command and the file_backup_path variable from sourcebroker/deployer-extended because it is not able to do create local backups, which is needed for our rsync.

The pull request for this change is still open.



  1. Add a backup host in deployer.php:

         ->set('deploy_path', '/home/backup/projectX')
  2. Add a custom pipeline in bitbucket-pipeline.yml:

         - step: &checkout-master
             name: Checkout master branch
             image: atlassian/default-image:2
               - .git/**
               - git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
               - git fetch origin
               - git checkout master
         - step: &install-deployer
             name: Install deployer
             image: composer:latest
               - composer
               - vendor/**
               - public/**
               - .env
               - composer install --no-ansi --no-interaction --no-progress --no-scripts --ignore-platform-reqs
           - step: *checkout-master
           - step: *install-deployer
           - step:
               image: drud/ddev-webserver:v1.17.6
               name: Backup database and rsync to HiDrive
                 - phpdismod xdebug
                 - ./vendor/bin/dep db:backup production --no-interaction
                 - ./vendor/bin/dep db:backup:rsync production --no-interaction
                 - ./vendor/bin/dep file:backup production --no-interaction
                 - ./vendor/bin/dep file:backup:rsync production --no-interaction
  3. Register a new scheduler

    pipeline example