Getting Started with Rocketeer to Simplify Deployments

Wouldn’t it be great if deploying changes to a server was as simple as typing the command rocketeer deploy? Well with Rocketeer it is!

Rocketeer is a task runner and deployment package. It is an alternative to the popular Capistrano.

So why use Rocketeer instead? Well Rocketeer is built using PHP whereas Capistrano is a Ruby package. If you mainly develop with PHP Rocketeer will simply be easier to work with as the config files will be more readable to you. Also, things like Composer and PHPUnit need to be configured with Capistrano whereas they’re integrated into the core Rocketeer deployment process.

Rocketeer can deploy anything from a small HTML/CSS site to a large Rails application, but the focus of this article will be deploying a Composer based PHP application.

Installing Rocketeer

So let’s get started.

Installing Rocketeer is pretty straightforward. Just open up a terminal and run the following three commands (I’m assuming you’re using either OSX or Linux here, other installation methods can be found in the official docs

$ wget http://rocketeer.autopergamene.eu/versions/rocketeer.phar
$ chmod +x rocketeer.phar
$ sudo mv rocketeer.phar /usr/local/bin/rocketeer

You might need to modify that last one if you want to install Rocketeer to a different location to the shown /usr/local/bin/rocketeer.

Configuring Rocketeer

With Rocketeer installed it’s time to start setting up a project to be deployed with it. Setting up Rocketeer is relatively simple. From the root folder of the project the you want to deploy run the following command:-

$ rocketeer ignite

Rocketeer will then ask a series of questions to setup the basics. Most of these should be relatively self explanatory, but I’ll quickly run through an example setup. (Please note that the questions asked may vary for you depending on your setup from the ones shown, but this example should give you some idea of what to expect).

The first question Rocketeer is likely to ask you is:-

No connections have been set, please create one: (production)

This is asking you to name the connection you want to setup. For example, ‘production’ or ‘staging’. Rocketeer uses named connections to define how to connect to a server. You can just hit Enter to use Rocketeer’s suggestion (which in this case is ‘production’).

We now need to tell Rocketeer where this server can be reached:-

No host is set for [production/0], please provide one:

For this enter either the address or IP address of the server you want to deploy to. This address is then stored against the connection you’ve just created.

Next we need to sort out the server login details:-

No username is set for [production/0], please provide one:

This is the username for logging onto the remote server. If you do not want to store this in the Rocketeer config files you can just skip it by pressing Enter. Providing a username here will avoid the need to enter one every time you deploy.

No password or SSH key is set for [production/0], which would you use? (key) [key/password]

This is asking what method you want to use for logging in to the host server, a password or via a SSH key. Select one or the other. You will then be prompted for corresponding details, either the password or the path to the key.

It is better to skip supplying a password by just pressing Enter if you plan on saving the Rocketeer config files to a repository. It is not a good idea to store plain text passwords that someone could unwantedly discover.

Finally, Rocketeer will ask you to name the application you want to deploy:-

What is your application's name ?

Rocketeer will create a folder of the same name in the root directory configured for your connection and deploy into it. This can be overridden (we’ll take a look at that in a bit).

Once the setup wizard has completed you should find a .rocketeer folder in the root directory of the project containing the config files.

---

The Config Files

Before we look at actually deploying the project let’s take a look at the config files the wizard has just created. The .rocketeer folder should contain the following files:-

• config.php
• hooks.php
• paths.php
• remote.php
• scm.php
• stages.php
• strategies.php

You’re free to edit these files to tailor the deployment process for your project. It’s a good idea to take a look through each of these files if it is your first time with Rocketeer to see what you can configure further. The files are really well commented so shouldn’t be too intimidating to look at.

config.php

This is the main configuration settings file. Much of what was provided during the wizard setup can be found in this file. You’ll see that the file basically just returns an array of settings.

All the available server connections are defined in this file as well as contextual options. The contextual options are for fine-tuning the configuration for a specific connection or stage.

hooks.php

This file is for defining tasks to be run on the server before and after you run a Rocketeer task like setup or deploy. The tasks defined here can be anything you’d run on the command line on the server. Tasks are defined as an array of commands.

paths.php

Rocketeer will attempt to find php and composer on the server itself, but if you need to give it a helping hand you can define the paths to these in the paths.php file. For example, to tell Rocketeer the path to PHP:-

'php' => '/usr/local/bin/php55',

remote.php

This file contains settings for the default remote server you are deploying to. There’s some pretty important settings in this file and many of these will need addressing before you make your first deployment.

The root_directory setting sets the path on the server that your apps are deployed to:-

'root_directory' => '/var/www/vhosts',

Make sure that you use the absolute path starting at the root folder on the server otherwise this won’t work.

By default, apps are deployed to a folder inside root_directory named after the app as defined by application_name in config.php; however, you can override this in remote.php using the app_directory setting:-

'app_directory' => 'example',

If you’re deploying a site that has content that must be kept between releases/deployments that are not tracked by your app’s repository then these need defining like this:-

'shared' => [
    'logs',
    'tmp/sessions',
    'config/app.php'
],

Note that these can be a combination of both folders and files. This is useful for keeping any content uploaded to the app like images and log files that you don’t want to lose.

You can also set file/folder permissions in this config file. Any file or folder that needs to be writeable can be defined like this:-

'permissions' => [
    // The folders and files to set as web writable
    'files'    => [
        'app/database/production.sqlite',
        'storage',
        'public',
    ],
],

scm.php

This is where details of the repository that your app is to be cloned from are stored. Rocketeer supports both Git and SVN. This file should be relatively self explanatory.

If you are using multiple connections or stages you will probably want to use contextual configurations to alter the default settings (we’ll discuss this in a bit).

By default we want to deploy from our repository’s master branch which you should find pre-defined in the scm.php file:-

// The branch to deploy
'branch' => 'master',

stages.php

Where connections represent different remote servers, stages are separate environments on a server. Stages are beyond the scope of this article, but basically this config file is where you define them.

strategies.php

The final file allows you to configure which tasks to use to execute various core parts of your deployment’s flow. For example, how to test code or run database migrations. Rocketeer is inspired by the Laravel framework so you will find that many of the tasks are initially set up to support deploying a Laravel project, but of course you can change these to suit your own needs should you find you need to.

Contextual Configuration

The settings defined in the config files represent the defaults to be used when deploying with Rocketeer. However, if you have multiple servers (connections) or stages your configurations are likely to vary a little for each. This is where the contextual options come in.

The contextual options can be found towards the bottom of the main config.php file. The options act as overrides for the default configurations from the other files using nested arrays.

For example, let’s consider a project configured to use two connections (e.g. ‘production’ and ‘staging’).

'on' => [
    // Stages configurations
    'stages' => [
    ],
    // Connections configuration
    'connections' => [
        'production' => [
            'scm' => [
                'branch' => 'master'
            ]
        ],
        'staging' => [
            'scm' => [
                'branch' => 'dev'
            ]
        ],
    ],
],

What is happening here is the branch setting in the scm.php config file is being overridden for the ‘production’ and ‘staging’ connections. If the master branch is already set in scm.php as the default branch we don’t need to override it for the ‘production’ connection, so the above can be simplified to:-

'on' => [
    // Stages configurations
    'stages' => [
    ],
    // Connections configuration
    'connections' => [
        'staging' => [
            'scm' => [
                'branch' => 'dev'
            ]
        ],
    ],
],

The contextual settings are grouped according to the connection or stage they relate to and then the name of the config file that the setting we’re overriding can be found in. So if we wanted to redefine the root_directory defined in remote.php for the staging connection we’d add ['remote']['root_directory'] to the options for ['on']['connections']['staging'] like this:-

'on' => [
    // Stages configurations
    'stages' => [
    ],
    // Connections configuration
    'connections' => [
        'staging' => [
            'remote' => [
                'root_directory' => '/home/example/www'
            ],
            'scm' => [
                'branch' => 'dev'
            ]
        ],
    ],
],

If the contextual options are becoming rather lengthy you can break these out into a file-based alternative as detailed in the docs.

---

Deployment

Once everything is configured the first thing to do before making your first deployment is to test your configuration and make sure that the server being deployed to is ready to receive the application. This can be done using the check task:-

$ rocketeer check

To deploy the default connection use deploy:-

$ rocketeer deploy

When Rocketeer deploys to the server it will clone the configured repository to a releases folder within the configured directory for the app and then create a symbolic link to this called current. If you’re project uses Composer (and the composer.lock file is in the root of your project) it will automatically run composer install as part of the deployment process.

If Rocketeer runs Composer then Composer must be installed on the remote server. If Rocketeer is struggling to find it on the server then you can set the path to it in either the paths.php file or via a contextual option in config.php.

If something goes wrong or you just want to restore the previous release you can use rollback to revert to the last deployment:-

$ rocketeer rollback

If you want to deploy to the staging connection use the --on flag:-

$ rocketeer deploy --on="staging"

It’s also possible to deploy to multiple connections in one go:-

$ rocketeer deploy --on="production,staging"

Once you’ve deployed to a remote server you should find a file structure in the apps directory on the server like this:-

• app_name/
  • current -> /var/www/vhosts/app_name/releases/20151117201500/
  • releases/
  • shared/
  • state.json

Where current is the symbolic link to the current release (this is what Apache, or whatever you are using, needs pointing at); releases contains deployed versions of your site (the most recent symbolically linked to by current). and shared contains any files or folders that should be kept by all releases as configured in remote.php.

If you’ve used Capistrano before then this file structure should be familiar.

Final Words

Rocketeer is a fantastic tool for simplifying the deployment process so that you can deploy in a single step. I’ve personally worked with both Capistrano and Rocketeer and as a PHP developer find the latter much easier to work with.

There is far too much to cover in a single article, but this should have given you a decent overview to getting started with Rocketeer. The best way to get started is to download it, run the wizard and take a look through the generated config files. Have fun!