Ghost theme version control and deployment with Capistrano, Git and BitBucket

Keeping your software under version control, using for example Git, Bazaar or Merurial is a good thing. Today it is easier than ever to version control your code using services like GitHub and Bitbucket so there is no excuse for not keeping your carefully crafted Ghost theme under version control. Connecting your Ghost theme repo with a deployment service or jacking into Capistrano or Fabric makes development and deployment easier and much more reliable than using FTP to shovel files or editing files directly on the server.

Disclaimer: This is a high level walkthrough on how to deploy a Ghost theme using Git, BitBucket and Capistrano following a [happy path](http://en.wikipedia.org/wiki/Happy_path). I don't go into technical details or advanced settings.

I’m basically using Bitbucket for all my personal projects and Capistrano to deploy them. Bitbucket since they allow me to have as many private repos as I want and Capistrano since it has been more or less the default way to deploy Rails applications and it also have decent support for non Rails and Ruby applications.

Deploying Ghost versus a Ghost theme is a bit different. It would be much easier to deploy the whole Ghost application than just a theme. However, I feel that it is a bit unnecessary to deploy the full application when all I want to do is to push and deploy changes to my theme, so that is, what I set out to do. Further down the road I see a need for a better setup than the one I went with.

At the moment Ghost is just not developed and mature enough to be deployed as a whole. That is my feeling at least, since there will be plenty of updates the coming months. When Ghost has matured and stabilized I see a need for both deployment and installation script, but that is anohter story. Now, lets deploy Ghost themes using Capistrano, Git and Bitbucket.

To deploy with Capistrano you need Ruby installed and either have your own server that you can access using SSH keys or be using something like Heroku or OpenShift. If you are hosting Ghost yourself using a VPS you are most likely already setup.

Ruby is best run using RVM and if you don’t use RVM I suggest you get started. The easiest way to install RVM is to run the following in a terminal window. If you are using Windows I suggest checking out pik

# Installs RVM and the latest version of Ruby
\curl -sSL https://get.rvm.io | bash -s stable

If the installation fails due to the lack of some missing lib or similar I suggest getting Homebrew if you are on OS X, Linux users can most likely use their package manager and Windows users, well I just don’t know.

When you have RVM installed verify that everything works by running.

# Should output the RVM help
rvm help

# Will list your available Ruby versions
rvm list

# Make sure you use your choosen version of Ruby, this will use ruby 2
rvm use 2.0.0

Next we want to create a specific Gemset for our deployment.

# Create a Gemset named ghost for Ruby 2
rvm use 2.0.0
rvm gemset create ghost
rvm use 2.0.0@ghost

Install Capistrano, for more detils read the docs

# Installs latest version of Capistrano
gem install capistrano

Now it is time to Capify our Ghost project, we will do this in the root directory of Ghost since it makes most sense to have the deployment information there. You could argue that it should be inside the theme directory, but we’ll settle for the Ghost root folder this time.

# Go into your ghost folder, something like
cd ghost

# Capify your Ghost project, make sure you are in your root folder of ghost and run the cap install command.
cap install

# This will create the following inside your ghost folder.
Capfile
config/deploy.rb
config/deploy/production.rb
config/deploy/staging.rb

The Capfile takes care of various things needed for Capistrano to run. Deploy.rb contains the main configuration and production.rb and staging.rb holds the server specific settings. Ok, now when we have Capistrano in place it is time to hook up our theme to Bitbucket using Git.

There are several way to setup a Git repo, this way is one of the easiest when using an external service. Go to Bitbucket and create a new repository and give it the same name as your theme and choose Git as repository type. What we want to do is to only version control our theme so open a terminal and go into your theme directory.

# Go into your Ghost theme folder, something like
cd ghost/content/themes/your-theme

# Create the Git repo on Bitbucket and follow the instructions
# If you are creating a repo from scratch it will be something like
git init
git remote add origin ssh://git@bitbucket.org/USERNAME/THEME-NAME.git
git add
git commit -m "inital commit"
git push origin master

Reload the Bitbucket page and your new repo should be there. Alright, we have our repo at Bitbucket and we have Capistrano installed and capified. Next up is to configure the deployment script in deploy.rb and production.rb.

Here is a minimal deploy.rb file that only contains what is needed for what we want to achieve, there are tons of more settings for Capistrano.

set :application, 'ghost'
set :repo_url, 'git@bitbucket.org:username/theme-name.git'
set :rvm_type, :user
set :rvm_ruby_version, '2.0.0@ghost'
set :deploy_to, '/var/webapps/ghost/content'
set :scm, :git
set :format, :pretty
set :log_level, :debug
set :keep_releases, 5

namespace :deploy do

  desc 'Restart application'
  task :restart do
    on roles(:web), in: :sequence, wait: 5 do
      within release_path do
        execute "NODE_ENV=production forever restart index.js"
      end
    end
  end

  desc 'Tasks before restart'
  before :restart, :clear_cache do
    on roles(:web), in: :groups, limit: 3, wait: 10 do
      execute "ln -s /var/webapps/ghost/content/current /var/webapps/ghost/content/themes/theme-name"
      execute "rm /var/webapps/ghost/content/themes/theme-name/current"
    end
  end

  after :finishing, 'deploy:cleanup'

end

Here is the production.rb also stripped down to a bare minium.

set :stage, :production
role :web, %w{username@example.com}
server 'example.com', user: 'username', roles: %w{web app}, ssh_options: {auth_methods: %w(publickey), port: 1234}

So far so good. Make a few changes to your Ghost theme and commit and upload them to BitBucket. I recommend that you use some kind of GUI tool like Tower or SourceTree instead of using the command line to handle Git, it is just easier and you also get some guidance. However, using and learning Git through command line is not a bad thing since you will get a better understand on how things work.

For Capistrano to work the server needs to be setup and Capistrano provides a few good tools for this. If your config file is correct and the specified users have the correct permissions it will go rather quickly.

cap production deploy:check

If it all checks out it is time for deployment and enjoy easy updates of your Ghost theme.

# Run the deploy command
cap production deploy

That’s it! Your are done!

comments powered by Disqus