Easy steps to deploy WordPress using Capistrano

First off I have been using git for my source control of late, partly due to gihub.com and also recent use of Heroku.com. Quick guides for git setup on your shared host and local dev machine are readily available but I found that the best guide for me was here, Gitn Your Shared Host On.

Remote Git Setup

Using a shared host, such as dreamhost you can easily setup a remote git repository that we can use later with Capistrano deployment.

ssh username@yourcheaphost.com
mkdir -p ~/git/yourproject.git
cd ~/git/yourproject.git
git --bare init

Local Git Setup

mkdir yourproject
cd yourproject
git init
git remote add origin ssh://username@yourcheaphost.com/~/git/yourproject.git
touch .gitignore
git add .
git commit -m "Initial Commit"
git push origin master

At this point you have now pushed to your remote repository and are almost good to go. The last thing is you need to add the following on your local machine to .git/config in your project.

[branch "master"]
remote = origin
merge = refs/heads/master

Local WordPress setup

Most likely you don’t need help with the local setup but I will share my setup.

In the same directory we setup our local git repository I extract the wordpress files.

- yourproject
-- wordpress
--- wp-admin
--- wp-content
--- wp-includes

Once you have extracted the current version of wordpress then I add the plugins and themes to the wp-content folder that I will be using in this project. At this time I will commit the changes and push them to the remote repository.

git commit -m "wordpress"
git push origin master

Depending on the secrecy/control needed you can use a gitignore file to skip the wp-config.php file if you want to keep passwords out of the repository. I will leave that up to you, I don’t address how to handle that in this guide.

With your wordpress website ready to go you can now begin to worry about how to deploy your code to the production server with ease. This is where Capistrano comes in.

Capistrano Setup

I have used Capistrano with some rails projects and it works well. Capistrano was built to work with Rails projects. So there are some tricks to get it working when deploying PHP or other non Rails projects.

cd yourproject
capify .

This creates two files, yourproject/Capfile and yourproject/config/deploy.rb.

The next thing I found was a great gem on github that built out Capistrano has a railsless resource. Check out the repository, http://github.com/leehambley/railsless-deploy/

gem install railsless-deploy

Once you have the gem installed you want to open up the Capfile and edit the contents.

load 'deploy' if respond_to?(:namespace) # cap2 differentiator
# Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }

require 'rubygems'
require 'railsless-deploy'
load    'config/deploy'

Then comes time to edit the deploy.rb file with your specific setup. Again much of this was extracted from other sources like Railstips.

default_run_options[:pty] = true

# be sure to change these
set :user, 'username'
set :domain, 'yourdomain.com'
set :application, 'yourapp'
set :wordpress_dir, 'wordpress'

# the rest should be good
set :repository,  "#{user}@#{domain}:git/#{application}.git"
set :deploy_to, "/home/#{user}/#{domain}"
set :deploy_via, :remote_cache
set :scm, 'git'
set :branch, 'master'
set :git_shallow_clone, 1
set :scm_verbose, true
set :use_sudo, false

server domain, :app, :web
role :db, domain, :primary => true

That is a basic portion of the deploy.rb file that works even with rails projects. For a wordpress project or other PHP source projects we need to make a few changes. I have added the wordpress_dir option for the cases when you deploy wordpress outside of the root directory. For me I usually install into a folder called blog. This will be needed for the next portion of the deploy.rb file.

In WordPress you have the wp-content/uploads directory which usually holds post photos and other media uploaded through the admin interface. We don’t want these to be lost each time we deploy the latest revision of the website so we need to create symlinks.

Here are the changes needed to make sure deployment of wordpress is handled correctly. Add these in the deploy.rb file below the previous code block.

set :app_symlinks, ["wp-content/uploads"]
before  'deploy:update_code', 'wordpress:symlinks:setup'
after   'deploy:symlink', 'wordpress:symlinks:update'

namespace :wordpress do
  namespace :symlinks do
    desc "Setup application symlinks in the public"
    task :setup, :roles => [:web] do
      if app_symlinks
        app_symlinks.each { |link| run "mkdir -p #{shared_path}/public/#{wordpress_dir}/#{link}" }
      end
    end

    desc "Link public directories to shared location."
    task :update, :roles => [:web] do
      if app_symlinks
        app_symlinks.each { |link| run "ln -nfs #{shared_path}/public/#{wordpress_dir}/#{link} #{current_path}/public/#{wordpress_dir}/#{link}" }
      end
      send(run_method, "rm -f #{current_path}/public/#{wordpress_dir}/wp-config.php")
      send(run_method, "ln -nfs #{shared_path}/public/#{wordpress_dir}/wp-config.php #{current_path}/public/#{wordpress_dir}/wp-config.php")
    end
  end
end

Painfully extracted this logic from http://madebymany.co.uk/using-capistrano-with-php-specifically-wordpress-0087. Wish the formatting was better on his site.

Setting up your server

At this point you need to make sure you server is ready to find the files. Capistrano will be looking to deploy symlinks to current/public. On Dreamhost you need to change the root of your server /home/username/yourdomain.com/current/public. This is the same setup when using a Passenger run Rails site. Once created then make sure to remove the current directory before attempting to deploy.

Deploy your application

Now that everything is ready you should be able to deploy the application.

cap deploy:setup

The setup should have created 2 new folders, shared and releases, in your domain directory on the remote host. If not check the output for any error messages. Once completed you are now ready to deploy your wordpress website.

cap deploy

At this point you should have a new Revision folder in your releases folder and the Current folder should be linked to that folder. Try opening your domain and see if you get to the wordpress site.

WordPress Tips

If you deployed outside of the root you might need to make sure to copy the wordpress/index.php file to the root directory. If your database isn’t setup then try using the yourdomain.com/wordpress/wp-admin to get to the install wizard.

Good Luck setting up your next WordPress project using Capistrano and git to make deployments even easier.