Make It Simple

Instead, make your deployment process a simple one-line command. A simple deployment process is less scary, and that means you’re more likely to push code to production.

Make It Predictable

Make your deployment process predictable. A predictable process is even less scary because you know exactly what it is going to do. It should not have unexpected side effects. If it runs into an error, it aborts the deployment process and leaves the existing codebase in place.

Make It Reversible

Make your deployment process reversible. If you accidentily push bad code into production, it should be a simple one-line command to roll back to the previous stable codebase. This is your safety net. A reversible deployment process should make you excited—not afraid—to push code into production. If you screw up, just roll back to the previous release.

How It Works

You install Capistrano on your local workstation. Capistrano deploys your PHP application to a remote server by issuing SSH commands from your local workstation to the remote server. Capistrano organizes application deployments in their own directories on the remote server. Capistrano maintains five or more application deployment directories in case you must roll back to an earlier release. Capistrano also creates a current/ directory that is a symlink to the current application deployment’s directory. Your production server’s Capistrano-managed directory structure might look like Example 9-1.

/
    home/
        deploy/
            apps/
                my_app/
                    current/
                    releases/
                        release1/
                        release2/
                        release3/
                        release4/
                        release5/

When you deploy a new application release to production, Capistrano first retrieves the latest version of your application code from its Git repository. Next, Capistrano places the application code in a new release directory. Finally, Capistrano symlinks the current/ directory to the new release directory. When you ask Capistrano to roll back to a previous release, Capistrano points the current/ directory symlink to a previous release directory. Capistrano is an elegant and simple deployment solution that makes PHP application deployments simple, predictable, and reversible.

Install

Install Capistrano on your local machine. Do not install Capistrano on your remote servers. You’ll need ruby and gem, too. OS X users already have these. Linux users can install ruby and gem with their respective package managers. After you install ruby and gem, install Capistrano with this command:

gem install capistrano

Configure

After you install Capistrano, you must initialize your project for Capistrano. Open a terminal, navigate to your project’s topmost directory, and run this command:

cap install

This command creates a file named Capfile, a directory named config/, and a directory named lib/. Your project’s topmost directory should now have these files and directories:

Capfile
config/
    deploy/
        production.rb
        staging.rb
    deploy.rb
lib/
    capistrano/
        tasks/

The Capfile file is Capistrano’s central configuration file, and it aggregates the configuration files located in the config/ directory. The config/ directory contains configuration files for each remote server environment (e.g., testing, staging, or production).

By default, Capistrano assumes you have multiple environments for your application. For example, you might have separate staging and production environments. Capistrano provides a separate configuration file for each environment in the config/deploy/ directory. Capistrano also provides the config/deploy.rb configuration file, which contains settings common to all environments.

In each environment, Capistrano has the notion of server roles. For example, your production environment may have a front-facing web server (the web role), an application server (the app role), and a database server (the db role). Only the largest applications necessitate this architecture. Smaller PHP applications generally use only one machine that runs the web server (nginx), application server (PHP-FPM), and database server (MariaDB).

For this demonstration, I’m only going to use Capistrano’s web role and ignore its app and db roles. Capistrano’s roles let you organize tasks to be executed only on servers that belong to a given role. This isn’t something we’re going to worry about here. However, I am going to respect Capistrano’s notion of server environments. This demonstration will use the production environment, but the following steps are equally applicable to other environments (e.g., staging or testing).

role :web, %w{deploy@123.456.78.90}

Authenticate

Before we deploy our application with Capistrano, we must establish authentication between our local computer and our remote servers, and between our remote servers and the Git repository. We already discussed how to set up SSH key-pair authentication between our local computer and remote server. You should also establish SSH key-pair authentication between your remote servers and the Git repository.

Use the same instructions we discussed earlier to generate an SSH public and private keypair on each remote server. The Git repository should have access to each remote server’s public key; both GitHub and Bitbucket let you add multiple public SSH keys to your user account. Ultimately, you must be able to clone the Git repository to your remote servers without a password.

Prepare the Remote Server

We’re almost ready to deploy our application. First, we need to prepare our remote server. Log in to your remote server with SSH and create the directory in which we’ll deploy our PHP application. This directory must be readable and writable by the deploy user. I like to create a directory for my applications in the deploy user’s home directory, like this:

/
    home/
        deploy/
            apps/
                my_app/

# Ubuntu
sudo apt-get install git;

# CentOS
sudo yum install git;

Capistrano Hooks

Capistrano allows us to run our own commands at specific moments (or hooks) during application deployment. Many PHP developers manage application dependencies with Composer. We can install Composer dependencies during each Capistrano deployment with a Capistrano hook. Open the config/deploy.rb file in your preferred text editor and append this Ruby code:

namespace :deploy do
  desc "Build"
  after :updated, :build do
      on roles(:web) do
          within release_path  do
            execute :composer, "install --no-dev --quiet"
          end
      end
  end
end

Our application’s dependencies are now installed automatically after each production deployment. You can read more about Capistrano hooks on the Capistrano website.

Deploy Your Application

Now’s the fun part! Make sure you’ve committed and pushed your most recent application code to your Git repository. Then open a terminal on your local computer and navigate to your application’s topmost directory. If you’ve done everything correctly, you can deploy your PHP application with this one-line command:

cap production deploy

Roll Back Your Application

In the off chance you deploy bad code to your production environment, you can roll back to a previous release with this one-line command:

cap production deploy:rollback