Installing Deployer


Right, now that you know a bit about Deployer and we've covered the series groundwork, let's get hands on with installing Deployer.

Like so many good PHP projects available today, there are a number of ways in which you can install it, specifically three; these are:

  • downloading the phar file
  • building the Deployer phar file from source
  • installing using Composer

Composer

I'll start with Composer, as that's my most preferred method. Though the phar file's not too far behind.

I'll assume that you have an existing project which you're wanting to integrate with.

I'll also assume that your project's using Composer, and that it has a composer.json file in the root of the project.

But if it's not, this will work all the same.

Here in the root of my project's directory, I'll run composer require deployer/deployer:~3.0, which adds Deployer to the require section of the file and adds the Deployer source to the vendor directory.

Once that's done, in vendor/bin you'll see a new file, called dep.

Download

Let's say you don't want to take that path, but want a self-contained binary. Whilst simpler, it's not my preferred method - but it works really well. In that case, download the Phar file from http://deployer.org/deployer.phar.

If you're not familiar with a Phar file, Phar files, or archives, are similar in concept to Java JAR archives, but are tailored to the needs and to the flexibility of PHP applications.

As the PHP manual says:

A Phar archive is used to distribute a complete PHP application or library in a single file. A Phar archive application is used exactly like any other PHP application.

I'll use wget to download the phar file, by calling wget http://deployer.org/deployer.phar.

Once the phar file's downloaded, we need to put it into a directory which is in the user's path. The simplest on a Linux/Unix system is /usr/local/bin.

I'll do that by moving it, and in the process renaming it to deployer.

Then all that needs to be done is to add execute permissions, which is done by running chmod +x /usr/local/bin/deployer.

Building from Source

Alternatively, if you want the latest, you can download and build the phar file from source. It's not strictly necessary, as the phar file has an option to run a self-update, like Composer. But for sakes of completeness, we'll go through the process.

Firstly, I'll clone the Deployer repository located at github.com/deployphp/deployer.git.

Then I’ll cd to the directory and run composer install, to bring in all of Deployer external dependencies.

With that done, I'll then run the build script, which is called build, which will build the self-contained phar file.

Then we need to install it. We can do this with the same process we followed when downloading the phar file, moving it into the user's path and then making it executable.

The Deployer Directory Structure

Now Deployer is installed and integrated with our project.

But before we can go any further, it's essential to get an understanding of the directory structure it creates .That way, the commands which you'll see later, will make more sense.

In a common deployment process, three top level directories are created. These are:

  • current
  • releases
  • shared

releases holds all of the releases, which are named with the timestamp of when they were created. This follows the format yyyymmddhhmmss. This is handy, and allows Deployer to rollback to previous releases, should you need to.

current is a symlink to the latest release, or to a rolled back release, assuming you rolled back one or more.

shared contains common files and directories, such as log and cache directories, shared files and so on. You don't have to use it, if your application isn't designed that way. But if you want to make full use of Deployer, it's handy to consider doing so.

Episodes