Automated workflow for deployment is a great tool that every software development team must have. The release process, when it is fast, secure and fault tolerant, can save time for developing more great things. And the good news that there are many great tools for creating an automated release cycle.

In this article, I'm going to introduce you a deployment tool called Deployer. I like to use it because it is written in PHP, is easy to set up, and has many handy features to integrate the deployment process into your team's workflow.

The Deployment Process With Deployer

First of all, let's see the structure of the deployment process with Deployer. It consists of three main parts: a deploy server to init deployment, a production or staging server to host your application, and a git repository to store the code of your application.

When you init a deploy process, you run a deployment script on the deploy server. After this, the deploy server connects to the production server with SSH and does the maintenance things from the production server like cloning the code from a git repository, updating Composer's dependencies, and other stuff you need in order to have a successful release. 

For everyone to be trusted in this chain, we will create and install SSH certificates to the servers and repository.

Install SSH Certificates

We need to create an SSH authentication key on a production server and share it to a git repository. If you don't have any SSH authentication keys on your deploy server, run ssh-keygen and follow the instructions. Keygen will create a public key in a file ~/.ssh/id_rsa.pub.

Now you can install it to the account of your repository. If you don't know how to do it, look at the example of GitHub from the related links at the bottom of the article, or ask your repository hosting service for help.

Also, it is better to create an SSH key on your deploy server to get trusted on the production machine. Use these commands to make a passwordless SSH connection between the deploy and production servers.

vagrant@localserver:~$ ssh-keygen
vagrant@localserver:~$ ssh-copy-id -i ~/.ssh/id_rsa.pub www-data@my_project.com

With all certificates installed, we are ready to install Deployer.

Install Deployer

The installation of Deployer is as easy as the installation of Composer. You need to download PHP Archive and make it a global command:

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

Let's check the version of Deployer to see if everything is installed correctly:

vagrant@localserver:~$ dep --version
Deployer 6.0.3

Everything looks great, and we are ready to create our first deployment script.

Make the First Deployment Script

To initialize Deployer for your project, run dep init. This will execute a utility to generate a deployment script, which will ask you for a project type and repository link and will create the deploy.php file in the current directory. Let's have a look at this file and the main functions that are used in a recipe. 

The functions set and get work with the configuration values, and a shortcut of a getter can be used with a run command:

set('current_path', '~/my_application');
run('rm {{current_path}}/runtime/*');

Each configuration value can be overridden for each host. We can set up a deploy path and SSH user for our application in our deploy script:

host('my_project.com')
    ->user('www-data')
    ->set('deploy_path', '~/{{application}}');

To define your own tasks, use the task function and run to run a command on the production server:

task('disk_free', function() {
    $df = run('df -h /');
    writeln($df);
});

And then run it with dep and the function name as a param:

vagrant@localserver:/vagrant/deployer$ dep disk_free
➤ Executing task disk_free
Filesystem      Size  Used Avail Use% Mounted on
/dev/md0        7.4G  4.7G  2.4G  67% /
✔ Ok

Now you can look through the deploy file and change all the needed params to the configuration of your application.

Deploy to Production

We have already installed Deployer, installed SSL certificates to the deploy and production servers, and made the deployment script, so finally it is time to pull it all together and make the first deployment to production.

To deploy your application, just call dep deploy:

If something has gone wrong, you can roll back to the previously deployed version in just one step:

vagrant@localserver:~$ dep rollback
✔ Executing task rollback

Looks easy, doesn't it?

Now let's check what was created on our production server. Thanks to Deployer, we can do this easily with shortcut commands. Try dep ssh to connect to a server directly using the configuration from the deployment script, or remotely execute a command via SSH tunnel with dep run. Also, this command supports variables that we have set in the script.

So let's have a look at the deploy path:

vagrant@localserver:~$ dep run "tree {{deploy_path}}"
.
├── current -> /home/user/my_project/releases/3
├── releases
│   ├── 1
│   │   ├── composer.json
│   │   ├── config.php -> /home/user/my_project/shared/config.php
│   │   ├── README.md
│   │   ├── runtime -> /home/user/data/my_project/shared/runtime
│   │   ├── vendor
│   │       └── ...
│   │   └── web
│   │       └── index.php
│   ├── 2
│   │   ...
│   └── 3
│       ...
└── shared
    ├── config.php
    └── runtime

The main thing is the releases directory, where Deployer stores the last versions of our application. After each successful deploy or rollback, it links current to the enabled release. Finally, we have a shared directory, which stores files and folders from the shared_dirs and shared_files that we have set in the script file.

On the first deployment, Deployer will copy those files to a shared dir and create a link from the releases dir to the shared dir. The next time, it will just add a link from the release files to the files and folders in the shared directory. Also, you can change any file in a shared directory and Deployer will keep it without changes on each deploy—for example, this is useful for configuration files.

In addition, if you have a composer.json file in the root of your repository, Deployer will call Composer to create a vendor directory and update all needed dependencies. If you don't store the Composer file in the root directory, you can create a custom task to update it.

And now it is time to integrate the application deploy to our processes.

Add a Custom Task

Every team has its own deploy configurations and process to automate, so Deployer has easy tools to extend the standard configuration and add custom tasks. For example, your hosting may have the rule to store applications and webroot in different places, with no rights to change the configuration of Apache or Nginx. 

But there is a way to get over this rule—use symbolic links. So we will add a task for this:

task('deploy:public_html', function() {
    run('ln -sf {{deploy_path}}/current/web /var/www/my_application.com');
});

And then add it to the main deploy task as part of a release cycle:

task('deploy', [
    // ...
    'deploy:public_html',
    // ...
]);

Now run the deploy script again and check if everything is correct with dep ssh.

Third-Party Recipes

Deployer has many recipes to integrate with third parties that can extend the basic functionality. We can use Composer to install them:

composer require deployer/recipes --dev 

I like to use the Slack notification recipe. To enable it, we should go to the Slack recipe page, click the Add to Slack button, and select the channel to send notifications. Then we will get the Slack webhook and add this code to deployment.

// require slack recipe
require 'recipe/slack.php';

// set slack webhook
set('slack_webhook', /* your slack webhook*/);

// notify slack after successful deploy
after('success', 'slack:notify:success');

After these changes, Deployer will send a message like this to the deploy channel:

Now you can add your team to the channel so everyone who's involved can be notified.

Conclusion

In this tutorial we have installed Deployer and created a deploy script that can be used to deploy our application from a git repository to a production or staging server in just one click.

Also, it can be integrated into team processes—for example, an application can be deployed automatically after changes in the master branch and notification can be made on a Slack channel about successful deployment.

If you have any questions, don't hesitate to ask questions in the comments to the article. 

Further Reading and Related Links

• Deployer's website
• Slack recipe for Deployer
• Example of installing an SSH key to a GitHub account