PHP deployer scripts for iw_master (TYPO3)
These Deployer Scripts contains build and deployment scripts for the task runner PHP Deployer.
All tasks are system independent (unix/windows) and are highly configurable., (*1)
The scripts are originally made for TYPO3 CMS and the distribution iw_master.
But you can deploy any application you want with these scripts, as well., (*2)
It's an early version currently, I'm happy about feedback and contributions Thanks :), (*3)
Key feature: league/flysystem
One cool thing of these Deployer Scripts is the awesome package league/flysystem which allows you to
perform file operations via SSH, FTP, on the local machine and some more., (*4)
Deployer Scripts provides the functions files() and filesLocally() in your tasks, which get
initialized automatically with the current server's configuration of deployer., (*5)
Installation
Just add instituteweb/deployer-scripts to your composer project:, (*6)
$ composer require instituteweb/deployer-scripts
This will also install deployer/deployer in your project., (*7)
Global installation
I can recommend to install PHP deployer globally and add vendor/bin directory in your home directory, to PATH variable., (*8)
$ composer global require instituteweb/deployer-scripts
In examples below I always write $ dep ..., assuming you also got it globally installed. If not, you need to write
$ bin/dep (iw_master) or $ vendor/bin/dep (composer default)... depending on your composer.json config (bin-dir)., (*9)
Configuration
PHP Deployer provides a pretty nice Environment handling, which allows us to set variables globally or for each
environment individually. The build and deploy configuration happens in deploy.php file in root of your project., (*10)
You need to include the common script of deployer-scripts. In common script all available tasks are included., (*11)
<?php
namespace Deployer;
require 'vendor/instituteweb/deployer-scripts/src/common.php';
// deployer.php kickstart template
If you have no experience with it, checkout the chapter tasks in documentation of Deployer., (*12)
General configuration parameters
Used binaries, like php, git, composer or unzip can have different calls on different environments., (*13)
<?php
set('bin/php', get('bin/php') ?: getenv('PHP_BIN') ?: 'php');
set('bin/git', get('bin/git') ?: getenv('GIT_BIN') ?: 'git');
set('bin/composer', get('bin/composer') ?: getenv('COMPOSER_BIN') ?: 'composer');
Many file operations are working well with flysystem, but some not. Removing and copying whole directories and
creating symlinks are such things. They use vsprintf()., (*14)
<?php
// File operations (unix)
set('bin/unzip', 'unzip -qo "%s" -d "%s"');
set('bin/rm', 'rm -rf %s');
set('bin/cp', 'cp -rf "%s" "%s"');
set('bin/symlink', 'ln -nfs %s %s');
set('bin/symlink-file', get('bin/symlink'));
For windows systems you can use these commands:, (*15)
<?php
// File operations (windows)
set('bin/rm', 'del /S /Q "%s"');
set('bin/cp', 'copy /Y /L "%s" "%s"');
set('bin/symlink', 'mklink /D %2$s %1$s');
set('bin/symlink-file', 'mklink %2$s %1$s');
There are more configuration parameters, but they are used for building or deploying. You find them below in
related section., (*16)
Build Scripts
Before we can deploy the project, we need to create a build. Deployer Scripts compresses all files to zip
archive, which can get deployed easily., (*17)
To create a build just call, (*18)
$ dep build
-
Create configured build directory (Default: ../.build, because git in git is not possible)
-
Update code using git. We define branch/tag or specific revision (default is master branch)
- Well, here we can execute frontend related stuff, like npm, bower and grunt/gulp.
No composer here, this should be executed on the system it run (because of symlinks and write/execution flags)
- Create the zip archive based on checked out and prepared release
-
Clear and remove checked out folder. Done.
This zip file is now able to get deployed., (*19)
Build and deploy can get called separately. If you want to execute it at once, you also can call, (*20)
$ dep build-deploy
Build config
build_dir
String. Folder to use for building the release. Relative from current working directory (cwd).
May not be already under git versioning. Default: ../.builds, (*21)
archive_list
Array. Key is path of directory and value path of zip file to create with contents of given key directory.
Default set('archive_list', ['{{build_path}}' => '{{build_dir}}/{{short_revision}}.zip']);, (*22)
git_repository
String. Path to your repository. You can also apply repos via SSH and access private repositories. Default: null, (*23)
git_branch
String. Branch or tag (both possible) to checkout. Default: master, (*24)
build_directory (readonly)
Returns absolute build_dir path., (*25)
build_path (readonly)
Returns absolute build_dir path with appended build_name., (*26)
build_name (readonly)
Returns build_name. If --name option is given it returns this value. Otherwise it takes the git_target value., (*27)
git_target (readonly)
Returns the given git_target. Default is master. You can influence this option with --branch or --tag option, or with
--revision option. Revision is also the first argument. You can call dep build-deploy 76b5410, (*28)
revision (readonly)
Returns the current git revision. Just available after build:update_code task or if revision is already given by command line., (*29)
short_revision (readonly)
Same like revision, but returns just the first seven digits of commit hash., (*30)
Deployment Scripts
This is an example structure of a deployed TYPO3 project:, (*31)
/html/typo3
├── .dep
│ └── releases.json
├── current -> releases/76b5410
├── releases
│ └── b2ff764
│ └── 1b61ee9
│ └── f9e80f1
│ └── e7059d1
│ └── 76b5410
└── shared
├── .env
└── web
└── fileadmin
└── typo3temp
└── uploads
To keep downtime very small during update and give you the possibility to roll to an earlier version back, in case
of heavy bugs after deploy, we work with releases (like Deployer itself does). Each deploy is a new release., (*32)
What happens during a deploy:, (*33)
$ dep deploy --revision 76b5410
-
Prepare initial folder structure on remote(s) on very first time
-
Lock deployer (to avoid parallel executions)
-
Upload zip file (76b5410.zip), which contains the build, to /releases
-
Extract the zip file to /releases/76b5410 (configurable, default: the git commit hash in short)
- Perform composer install within the new release
- Moves configured shared files and folders to /shared directory, deletes them in e.g. /releases/76b5410 and create
instead symlinks to the shared folders
-
Rollout the release, which switches /current symlink to new release
- Perform composer run post-update-cmd which performs TYPO3 tasks (update db schema, clear cache, ...)
-
Unlock deployer. We are done :)
Deploy config
composer_action
String. The command of composer which should be executed on server. Usually install or update. Default: install, (*34)
composer_options
String. Append options to composer to use, when get executed on remote machine.
Default: {{composer_action}} --prefer-dist --no-progress --no-suggest --no-interaction --no-dev --optimize-autoloader, (*35)
release_name
String. The name of the release. Default {{build_name}}, (*36)
release_path
String. Path on remote to upload and extract release to. Default: {{deploy_path}}/releases/{{release_name}}, (*37)
max_release_cycle
Integer. Amount of release to remain on remote system. Default: 5, (*38)
use_symlink_for_current
Boolean. If true the /current directory, which is used by webserver (htdocs), is a symlink. If provider is not
supporting symlinks here, you can disable the option. The current folder gets copied then, from release. Default: true, (*39)
upload_list
Array. Key is local source file and value is remote destination. File get uploaded. And if zip file it get also
extracted into a folder, named like the zip archive. Default:
['{{build_dir}}/{{short_revision}}.zip' => '{{deploy_path}}/releases/{{release_name}}.zip'], (*40)
directory_permissions
Integer. Unix directory permissions. Used for SSH connections (on remotes) only. Default: 0755, (*41)
Rollback
In case you need to roll back to a previous version you can do that, with:, (*42)
$ dep rollback [to]
You can set to argument to release name. By default it rolls back to previous release.
All releases are stored in .dep/release.json file. To show available release names use dep list-releases., (*43)
Run scripts
You can run a full deploy with this command:, (*44)
$ dep build-deploy [stage] [--revision]
$ dep build [stage] [--revision|--branch|--name]
$ dep deploy [stage] [--revision]
Argument revision is for deploy required and expects a {{revision}}.zip file in build_dir., (*45)
Arguments and options
stage argument
Run tasks only on this server or group of servers., (*46)
--revision
Specify a certain commit to build and release., (*47)
--tag or --branch
Does both the same. Sets tag or branch., (*48)
--name
Set the build name (which is also release name)., (*49)
--force
If set the .lock file on remote is ignored. Use this just in case your previous deployment failed., (*50)
Convenience tasks
To see the local builds and the remote releases (including which is the current one) you can use these commands:, (*51)
$ dep list-builds
➤ Executing task list-builds
Found builds in "C:\Dev\.builds":
- bbc2760
✔ Ok
$ dep list-releases
➤ Executing task list-releases
Max release cycle count: 5
Found releases on "production":
#0
Name: bbc2760
Path: /html/releases/bbc2760
Date: Sun, 15 Jan 2017 21:35:20 +0100
#1
Name: bbc2760_7
Path: /html/releases/bbc2760_7
Date: Sun, 15 Jan 2017 21:40:07 +0100
#2
Name: bbc2760_8
Path: /html/releases/bbc2760_8
Date: Sun, 15 Jan 2017 21:44:34 +0100
#3
Name: bbc2760_9
Path: /html/releases/bbc2760_9
Date: Sun, 15 Jan 2017 21:44:52 +0100
#10 +++ CURRENT RELEASE! +++
Name: bbc2760_10
Path: /html/releases/bbc2760_10
Date: Fri, 20 Jan 2017 13:26:57 +0100
✔ Ok
Notice: This happens (_7, _8, etc.) when you upload the same build multiple times., (*52)
Wallogit.com
