Introduction
Deploying applications to production/live servers is always a delicate task. The whole process needs to be quick to minimize downtime. Automating the deployment process helps running repetitive tasks minimizing the possibility human error. It is also a good idea to have a proven and easy way to rollback to a previous version if something goes wrong.
Capistrano and more specifically Capifony can help with the automatic deployment of symfony projects.
What is Capistrano?
Capistrano is a time saving command line tool, written in Ruby, that helps you execute automated tasks on remote servers from your local environment. It also allows you to run symfony commands. Capistrano was built to help you administer all your servers from one place, running commands, installing software and keeping everything in sync. Oh… and of course it has a rollback mechanism.
It’s one of those tools Ruby developers have that we often wish we had in symfony, and now we do. Enter Capifony…
Capistrano commands
Capistrano has 2 base commands:
1. `capify …`;
2. `cap …`.
Capify will create 2 files in a specified path (1st argument of `capify`):
1. `Capfile` – capistrano loader. It loads all basic libraries & project config file;
2. `config/deploy.rb` – project config file. Your configs & variables setup for project placed here.
The second command, `cap`, actually runs capistrano tasks on the remote server with config from your `config/deploy.rb`.
A capistrano recipe is a package of tasks, grouped into namespaces. You can use embedded tasks or write your own (place them in your `config/deploy.rb`). Once a task is written you can run it with `cap` command under your project directory:
cap namespace:task
Deployment recipe
—————–
As mentioned above, Capistrano is typically used to deploy Ruby On Rails applications. How does it work? Basically, capistrano must know 4 things:
1. addresses of your web, app & db servers (most often it’s the same address);
2. address of your source code control system repository (if you have one).
Keep in mind, that capistrano uses SSH to run remote tasks so you will need to have shell access to all your remote servers.
During the deploment process, Capistrano will maintain different files & directories on server. It will create a `releases` directory that has dated directories with the actual copy of your code for each release. In addition, Capistrano symlinks your shared folders (common between releases) into release directories, so logs, assets & other files keeps the same between deployments.
What is Capifony?
Capifony is a new RubyGem package, that extends Capistrano functionality so it can work with symfony PHP projects. In essence it’s a package of custom and extended original capistrano recipes.
Demo project
To fully understand how capifony works and what it does we need to create one simple symfony application and deploy it to our test server.
Step 1: Install
I assume that you already have Ruby & RubyGems installed on your local environment (MacOS X has this out of the box – simply update gems with `sudo gem update –system`).
To install capifony and capistrano, simply run:
gem install capifony
This command will install capifony and it’s dependencies (capistrano for example) to your local host. NOTE: Your local host is the only place where you need to install capifony & capistrano.
It’s also good practice to create and copy the SSH key to speed up the connections to your remote repositories.
Generate key with:
ssh-keygen -t rsa
Next, copy your public key to remote server that you want to connect to (I am going to assume your SSH user is called `demoUser`):
cat .ssh/id_rsa.pub | ssh demoUser@your.domain.com "cat >> .ssh/authorized_keys2"
Then just try to connect with:
ssh demoUser@your.domain.com
If all goes well the remote server will just let you in without password prompt.
We then need to create the project repository on server, so let’s create one:
ssh demoUser@your.domain.com
sudo mkdir /var/repos
sudo chown demoUser !$
cd !$
mkdir demo.git
cd !$
git --bare init
Step 2: Symfony project setup
Lets create empty git repository for our new demo site (we will use git as SCM, but you can use subversion or any other source code manager that’s supported by capistrano):
cd /var/www
mkdir demo
cd !$
git init
touch .gitignore
Now add these lines to your `.gitignore` to exclude asset symlinks, databases config, cache, backups, uploads & log folders from our git repository:
web/sf*
web/uploads/*
cache/*
plugins/.*
log/*
config/databases.yml
mkmf.log
.rsync*
backups/*
It’s time to add `.gitignore` to stage and make our initial commit:
git add .gitignore
git commit -m 'initial commit'
Finally we can generate skeleton for our demo project and commit it:
symfony generate:project demo
git add .
git commit -m 'symfony project created'
Now lets add the database schema to `config/doctrine/schema.yml`:
---
Topic:
actAs:
Timestampable: ~
columns:
id:
type: integer(4)
primary: true
autoincrement: true
title:
type: string(256)
notnull: true
content:
type: clob
notnull: true
And add some fixtures into `data/fixtures/fixtures.yml`:
Topic:
topic1:
title: First topic
content: first topic content
topic2:
title: Second topic
content: second topic content
topic3:
title: Third topic
content: third topic content
Build database and model files:
symfony doctrine:build --all --and-load --no-confirmation
And you need to generate the `frontend` application and put `main` module in it:
symfony generate:app frontend
symfony generate:module !$ main
To make this more interesting let’s put some logic for our application. Go to `apps/frontend/modules/main/actions/actions.class.php` and replace the `executeIndex` function code with this:
/**
* Executes index action
*
* @param sfRequest $request A request object
*/
public function executeIndex(sfWebRequest $request)
{
$this->topics = Doctrine::getTable('Topic')->findAll();
}
And the view. Go to `apps/frontend/modules/main/templates/indexSuccess.php` and add:
<dl>
<?php foreach ($topics as $topic): ?>
<dt><?php echo $topic->getTitle() ?></dt>
<dd>
<?php echo $topic->getContent() ?>
</dd>
<?php endforeach; ?>
</dl>
Now if you open http://your.local.demo.host/frontend_dev.php/main in browser you will se definition list with our 3 topics.
Add changes to git:
git add .
git commit -m 'finished project'
Stage 3: symfony library with project
It’s good practice to include the dependent version of symfony in your project repository. You can do this in two ways:
1. Simply copy symfony library under `lib/vendor/symfony` directory & commit it;
or
2. Submodule symfony library from another repository.
I like second way. To do this, we will submodule Vincent Jousse’s symfony 1.4 git mirror:
git submodule add http://github.com/vjousse/symfony-1.4.git lib/vendor/symfony
Don’t forget to fix symfony path in `config/ProjectConfiguration.class.php` (after both ways) from:
require_once '/opt/local/lib/php/symfony14/lib/autoload/sfCoreAutoload.class.php';
to
require_once dirname(__FILE__) . '/../lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php';
And commit this:
git add .
git commit -m 'bundled symfony'
Step 4: Push local project to remote git repository
Remember our `demo.git` repository on `demoUser@your.domain.com` that we’ve created earlier? It’s time to push our project to it:
git remote add origin ssh://demoUser@your.domain.com/var/repos/demo.git
git push origin master:refs/heads/master
Now your project is pushed to remote repository, where anyone who has SSH access can push/pull it. Also, we will use this repository to deploy new versions with capistrano.
Step 5: Config
Now is the time to play with capifony itself. First of all, lets “capifony” our project:
capifony .
Capifony created `Capfile` and `config/deploy.rb`. Go into `config/deploy.rb` and edit it’s variables. To set capistrano config variables, you need to call `set :var_name, “var_value”` instruction inside `deploy.rb`. Below is the list of main variables:
* `:application` – set your application name here (“demo” in our case);
* `:domain` – domain of our remote server. This variable will be auto-populated with `#{application}.com` (demo.com in our case). Place your server address here if it’s not `demo.com`. I set it to `#{application}.everzet.com`, because my test host is http://demo.everzet.com;
* `:deploy_to` – path, where we will deploy our application (in most cases `/var/www/#{domain}`);
* `:repository` – path to repository (`#{domain}:/var/repos/#{application}.git` in our case);
* `:scm` – source code management tool. In our case set it to `:git`, but it can be any of `accurev`, `bzr`, `cvs`, `darcs`, `subversion`, `mercurial`, `perforce`, `subversion` or even `none`;
* `:use_sudo` – set to `false`, because we doesn’t need sudo during our deployment process;
* `:deploy_via` – set it to `:remote_cache`, so deployments will last less time;
* `:git_enable_submodules` – set it to `1` if you have submodules in project (if you staged symfony as submodule for example);
Also add this line to `config/deploy.rb`:
ssh_options[:forward_agent] = true
if you want to use your local SSH key instead of remote one for git checkout.
Your resulting `config/deploy.rb` is must be something like this:
set :application, "demo"
set :domain, "#{application}.everzet.com"
set :deploy_to, "/var/www/#{domain}"
set :scm, :git
set :git_enable_submodules, 1
set :repository, "#{domain}:/var/repos/#{application}.git"
set :deploy_via, :remote_cache
role :web, domain
role :app, domain
role :db, domain, :primary => true
set :use_sudo, false
set :keep_releases, 3
ssh_options[:forward_agent] = true
Step 6: Deployment
To start, we need to know 3 basic capistrano commands:
1. `cap deploy:setup` – create directories on server;
2. `cap deploy:cold` – copy code, build database, make symlinks;
3. `cap deploy` – copy code, make symlinks.
Now run:
cap deploy:setup
This command will create the following folder structure on your server:
`-- /var/www/demo.everzet.com
|-- releases
`-- shared
|-- log
`-- web
`-- uploads
After few deployments, folder structure will eventually become something like this:
`-- /var/www/demo.everzet.com
|-- current (symlink)
|-- releases
|-- 20100512131539
|-- 20100509150741
`-- 20100509145325
`-- shared
|-- log
|-- config
`-- databases.yml
`-- web
`-- uploads
What does all this mean?
1. `releases` is folder, where all your releases sits. Every release is a timestamped folder under `releases` directory.
2. Every release has symlink to shared files and folders, placed in `shared` directory. This files & folders stays same between deploys;
3. capistrano creates symlink to latest release, called `current`. This is your current project folder to work with (where to point web servers, crontabs etc.).
Now lets deploy our application for the first time:
cap deploy:cold
If you’ve configured your remote server hosts right, you now can open http://your.remote.host/main & see you symfony application there.
Step 7: Deploy & Rollback
Now what if we change something, deployed it and it’s broke our site? Lets break something!
Open `apps/frontend/modules/main/actions/actions.class.php` and change
$this->topics = Doctrine::getTable('Topic')->findAll();
to
$this->topics = Doctrine::getTable('TopicS')->findAll();
Save it, commit it and push to remote repository:
git add .
git commit -m 'buggy change'
git push origin master
Now deploy this bug:
cap deploy
and try to open http://your.remote.host/main. Oh, no! Something broke. What to do? Simple! Run:
cap deploy:rollback
and capistrano will roll your server back to previous working version of project and you will be able to find, fix, push and deploy the bugfix later, without problems.
Conclusion
Capistrano is mighty tool that has served RoR developers for many years. Now the symfony world can use these best practices in their development workflow. It’s as simple as installing capifony gem.
If you want to add/request something or read further manuals – please, visit project repository on github.
About the Author
Konstantin Kudryashov (aka everzet) is a web developer from Minsk, Belarus. Most of the time, he builds symfony applications. When he’s not – he maintains symfony bundles for TextMate, writes symfony plugins & php libraries.
Another great symfony conference is happening this July, “Jornadas de symfony”, and might we add, it’s our favorite type of day. The free conference will last two days and takes place at the Castellon University near Valencia, and is limited to 170 people. The lineup looks fantastic.
