Using Rocketeer for Easy Deployment to VPS

In this blog, I will be referring to Laravel deployments in particular; however, Rocketeer was designed to be framework agnostic and so the general principles should be transferrable to any deployment scenario.

The primary goal of Rocketeer is to interface with your source code manager (SCM) and transfer code (from your SCM) to your deployment folder. It is important that you understand this – Rocketeer does NOT transfer code directly via ssh/scp. You MUST use an SCM (git/cvn). In the Laravel context, It also performs other tasks like running migrations, installing composer dependencies etc.

The flexibility provided by Rocketeer is particularly enticing in a VPS scenario. There are a couple of gotchas that you need to be aware of especially when using your own VPS as a github repo. Listed below are the steps I take to deploy Laravel apps to my VPS.

Step 1: Prep the laravel app under question – Include the dependency on rocketeer, add the provider and finally add and commit all code to your local git repository.

Step 2: Prep the remote VPS:

a. I will proceed with the assumption that you have hardened your VPS along the same lines as outlined in this great post by Bryan Kennedy. This means that you will ssh into your box using a predefined username and a key file (as against root+password).

b. From following step1, you must have added your local box ssh key to your hosts “.ssh/authorized_keys” file. Since Rocketeer will attempt to open an ssh channel to do a git clone, you must ADDITIONALLY generate a public key for your server and add it into the authorized_keys file. This is easily done by executing the following in your host:

ssh-keygen -t rsa -C "email@domain.com"

Accept the defaults. Then copy the contents of the generated .ssh/id_rsa.pub to your .ssh/authorized_keys file.

If the above is not properly done, the error message thrown by Rocketeer during the deploy process is:

Unable to clone the repository
Cloning into '/var/www/project1/releases/20140330095757'...
Permission denied (publickey).
fatal: The remote end hung up unexpectedly
Deployment was canceled by task "Deploy"
Execution time: 3.492s

c. Insure you have composer (globally) and git installed on your vps

d. Set up a directory structure convention for your projects (you will do this for each new project). Let’s say

  • Your project files get deployed to /var/www/project1
  • Your git repo is at /var/git/project1.git

Important: Since files will be deployed using the username you use to ssh, please also make sure that the username is in www-data group,and the www-data group has rwx permissions on /var/www. Do the same for the git folder as well.

e. Setup a git repository on your vps (/var/git/project1.git) and set the remote server option in your local repo

cd /var/git/project1.git
git init

on your local repo:

$ git remote add origin ssh://username@my.server.org/var/git/project1.git

Note how I specified my VPS hosted git repository. ‘username’ is the username that has ssh permissions to my vps. Rocketeer will login as this username and attempt to do a git clone in the deployment directory.

Run the following command to ensure that the remote server is properly set:

$ git remote -v
origin  ssh://username@my.server.org/var/git/project1.git (fetch)
origin  ssh://username@my.server.org/var/git/project1.git (push)

Note that you can use an IP address if you do not have a hostname associated with your VPS. After the remote server is set, you should be able to do:

$git push origin master

to push your code to your server repository.

Step 3: You are now ready to deploy apps to your vps using Rocketeer. Rocketeer uses the new Laravel 4.1 RemoteManager component (https://github.com/illuminate/remote). This requires a more recent version version of PHP.

Fill in the appropriate details in app/config/remote.php (Rocketeer pulls information from this config file into its own config.php file)

'connections' => array(
    'production' => array(
    'host'      => 'my.server.org',
    'username'  => ‘username’,
    'password'  => '',
    'key'       => '/home/vagrant/.ssh/id_rsa',
    'keyphrase' => '',
    'root'      => '/var/www',
    ),
),

On running php artisan, you should see the following Rocketeer specific options like so:

deploy
 deploy:check Check if the server is ready to receive the application
 deploy:cleanup Clean up old releases from the server.
 deploy:current Display what the current release is
 deploy:deploy Deploy the website.
 deploy:flush Flushes Rocketeer's cache of credentials
 deploy:ignite Creates Rocketeer's configuration
 deploy:rollback Rollback to the previous release, or to a specific one
 deploy:setup Set up the remote server for deployment
 deploy:teardown Remove the remote applications and existing caches
 deploy:test Run the tests on the server and displays the output
 deploy:update Update the remote server without doing a new release.

Start off the process (this is a once per project setup of config options) by typing

$ php artisan deploy:ignite
No repository is set for the repository, please provide one :ssh://username@my.server.org/var/git/project1.git
Configuration published for package: anahkiasen/rocketeer
What is your application's name ? (project1)
The Rocketeer configuration was created at anahkiasen/rocketeer
Execution time: 7.4155s

Go through the \config\packages\anahkiasen\rocketeer\remote.php file and ensure that the settings are correct.

I had to make a couple of changes:

'root_directory'   => '/home/www/', to
'root_directory'   => '/var/www/',

Also I commented out the ‘composer self-update’ task (this is because I have composer installed globally in the /usr/local/bin directory and the username that rocketeer uses to ssh does not have appropriate permissions to the folder for the composer self-update process)

// The process that will be executed by Composer
 'composer' => function ($task) {
 return array(
 //$task->composer('self-update'),
 $task->composer('install --no-interaction --no-dev --prefer-dist'),
 );
 },

Run the deploy:check command to verify that you are good to go.

$ php artisan deploy:check
Checking presence of git
Checking presence of Composer
Checking presence of mcrypt extension
Checking presence of mysql extension
Checking presence of pdo_mysql extension
Your server is ready to deploy
Execution time: 3.1507s

If any deficiencies are noted, please fix them prior to proceeding.

 Once you are ready to deploy. Type in

$ php artisan deploy

or

$ php artisan deploy:deploy

If all goes well, you should get a success message from Rocketeer and a copy of your code on the host VPS.

To troubleshoot the deploy process, type in

$ php artisan deploy --verbose

The –verbose switch will display a wealth of information to help you debug the source of the error.

We have barely scratched the surface of Rocketeer (although it covers the most common use-case). Be sure to read up the wiki to understand what exactly happens during a “deploy” and to implement more intricate deployment scenarios.

On a related note, I would also like to mention that git deployments can be accomplished using git post-receive hooks. There is a great tutorial explaining the process at digital ocean. Personally I prefer the Rocketeer way as it is easier to implement and also offers a simple version switching mechanism.

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s