This time, we will see how a very basic deployment recipe for TYPO3.Surf looks like.
The deployment recipes are basically PHP files which are stored in „Build/Surf/“.
# setup FLOW3/Surf like shown in Part 1: http://etobi.de/blog/2012/05/deployment-setup-typo3-surf/ cd SurfNTurf ls -l Build/Surf/
The TYPO3.Surf package ships with two preinstalled recipes: „flow3base-distribution.php“ and „phoenix-distribution.php“. These are not very „simple“, so we just ignore them for now.
Create your first deployment recipe
Start by creating a new file „foobar.php“ in „Build/Surf/“ and open it in your favorite editor.
When Surf executes our „foobar“ deployment, it will provide an instance of \TYPO3\Surf\Domain\Model\Deployment called $deployment within our recipe file. To get proper code completion for it (e.g. if you use PHPStorm), we start by adding a @var annotation for $deployment.
* Deployment configuration for "foobar"
/** @var $deployment \TYPO3\Surf\Domain\Model\Deployment */
Surf need to know how to do the deployment. So we’re setting up a „workflow„. A workflow defines the „stages“ which happen during the deployment. These stages might be e.g. „initialize“, „update“, „test“, „switch“, „cleanup“. Surf will execute each stage one after the other and can decide after each stage to abort and rollback the deployment, or to continue with the next stage.
In our case we’re using a „SimpleWorkflow“, which is provided by TYPO3.Surf. It’s instanciated and assigned to the $deployment. Simple as this:
// setup the workflow
$workflow = new \TYPO3\Surf\Domain\Model\SimpleWorkflow();
Next the deployment needs to know, what to deploy. For that, we create an „application“ instance and add it to the deployment.
The application defines, which actual tasks need to be executed in each stage of the workflow. The single tasks defined in this application might be for example „checkout the code from a git repository“.
In our example we’ll create a „BasicApplication“ and add it to the $deployment. The application gets an title in the constructor, so we can identify it easily in the logs later. Some tasks will need configuration, like we configure the path to the git repository and the base deployment path (where we want to deploy to).
// setup the application
$application = new \TYPO3\Surf\Application\BaseApplication('foobarApp');
Surf supports to deploy the same application with the same workflow to multiple servers with just one deployment run. So we need to tell TYPO3.Surf to which server/node we like to deploy our application to.
We create a „\TYPO3\Surf\Domain\Model\Node“ and give it a name („integration“) for the logging. The configuration of the node basically contains the hostname („int.example.com“). This will used to connect via ssh and execute the remote commands for the single tasks.
// setup the target host
$node = new \TYPO3\Surf\Domain\Model\Node('integration');
If your ssh connection needs a special username or an unusual port, you might want to add the following lines to set those.
'username' => 'johndoe',
// 'port' => '22',
// 'password' => '', # avoid using password authentication, better use auth using a private/public key
Run the deployment
Now we have a basic reciped which we can use do run Surf. Remember to adjust the configuration for your needs (like the hostname, path and repository url).
# show some informations about the deployment ./flow3 surf:describe foobar # 'dry-run' the deployment, to see what will be done. ./flow3 surf:simulate foobar # actually run the deployment ./flow3 surf:deploy foobar
If everything works out, you will find the deployed application in „/var/www/foobar/“ on the host „int.example.com“.
See what’s happened
Lets have a look into the target directory:
ssh int.example.com cd /var/www/foobar/ tree -L 2
. ├── cache │ └── localgitclone ├── releases │ ├── 20120925171518 │ ├── 20120925171518REVISION │ └── current -> ./20120925171518 └── shared
The folder „cache“ holds a local clone of your git repository.
In „releases“ you will find one subfolder for each deployment (named by the time the deployment happened). Further there is a symlink called „current“ which points to the latest successful release. When configuring your virtual host in the webserver, „current“ is the path your document root should point to.
If you run another deployment later, you will notice another symlink called „previous“. It points to the.. well.. previous release. You might want to setup an additional virtual host, which shows the previous version of the application.
Also, during the actual deployment, while TYPO3.Surf is running, there is third symlink called „next“. This will point the the release TYPO3.Surf is currently working on. This can be very helpful fo testing and several automated checks.
Last but not least you have and (currently) empty folder called „shared“. This is the place for everything, which is not specific for a single release, but should be the same for all releases. Think of assets/uploaded files or specific configuration, which is not versioned in your git repository. These can be stored once in „shared“ and e.g. symlinked into the release folders.
That’s it. Have fun exprimenting with TYPO3.Surf and setup your first own deployment.