Search

For the unfamiliar, Capistrano is a ruby library that makes deployment dead simple. By using Capistrano to manage your Symphony installation, it is possible to completely manage the Symphony deployment process, checking out the latest code, pushing it to the server. This eliminates the need for file transfers, server-side activities, and in-place/in-browser code editing. I use a variation of the setup below on all my projects, and it’s saved a heap of time (and my butt more than once).

Setup

Before we get going, you’ll need to make sure you’ve done the following:

  • Install Git and Capistrano locally
  • Ensure your application code is in a remote repository (like Github)
  • Install Git on the server
  • Ensure the deployment user on your server has SSH access to your repository
  • git clone the Capfile from http://github.com/makenosound/symphony-capistrano or download the file attached to this discussion

There are number of guides out there to getting setup with git and Capistrano, so I won’t bother going into that here.

Getting started

First things first. Capistrano checks for a Capfile in the directory you’re running from and uses that to read and execute tasks. Normally to add Capistrano to a project you’d run capify . in your project directory, but as it’s setup to work out with Rails conventions, setting up that way creates some unnecessary separation in your deployment script. For Symphony deployment we can just drop the Capfile from this repository into your project root on your local machine. The Capfile is written in ruby and contains the tasks we’ll use to deploy your site.

As we’re using an automated script for deployment, we make some assumptions about the setup of your project. This is pretty much in line with the basic setup that Capistrano uses, but with a few Symphony-specific tweaks. If you’re serving multiple sites on a shared server, or can’t modify your VirtualHosts in Apache I’d set up a sites/ directory to deploy your project into so that you end up with something resembling the directory structure below:

  ~/
    /sites
      /example.com

Next you’ll need to update the setting in the Capfile. You’ll need to set the following:

  • :application — the URL of your site, is used for establishing the ssh connection and (by convention) as the folder name for deploying into
  • :deploy_to — the folder we’re deploying into, note that we can use the application variable set above, or set an absolute path
  • :repository — the git-clone URL of your repository
  • :branch — the branch you want to check out, default is master
  • :user — the user account on your server

Once you have those things set up, just run the following command…

cap deploy:setup

…from your local machine and Capistrano should log into your server and build up the folder structure ready for checking out your code. There are a number of other options you can setup (just read through the Capfile), but you should be able to use the defaults. If everything ran smoothly you should have something like the following on your server:

~/
  /sites
    /example.com
      /releases  
      /shared  
        /log  
        /manifest  
           /cache  
           /dump  
           /logs  
           /tmp  
           config.php  
        /media
        /pids  
        /system

What we have here is the basic Capistrano setup. An application folder (~/example.com/) with a releases/ folder that will contain the timestamped releases of our application code and a shared/ folder that contains files that are shared between releases. I keep the manifest/ (configuration) files in here as well as a media/ folder for user-uploaded content — the shared/media/ folder will be symlinked into the latest release once we get to that stage.

If you’re using a different setup for your media/uploads then you’ll need to modify the recipe. I should also mention here that we’re going to be symlinking the entire shared/manifest/ folder from the root project folder once we deploy, so you’ll need to exclude that entire directory from your git repository (along with your workspace/media/). Obviously you’ll want to keep some of your configuration in git, so I usually create a config/ folder in my repository with a config.example.php file as well as any other config files that we’ll need (such as JIT or CacheLite config files).

Also, the way I setup my projects is to have the root Symphony folder at the root of my git repository so if you have your Symphony directory in a subfolder of your repository then you’ll have to change the recipe.

Deployment

OK. If you’re still with me we can get onto deployment. Assuming everything above went fine, all we need to do is…

cap deploy

…and you should see Capistrano go to work logging into your server and checking out your code. Again, assuming everything went smoothly you should now see something along the lines of the below on your server:

~/
  /sites
    /example.com
      /current
      /releases  
        /20100916050732  
          Your Symphony files!
      /shared  
        /log  
        /manifest  
           /cache  
           /dump  
           /logs  
           /tmp  
           config.php  
        /media
        /pids  
        /system

Note that we now have a current/ directory. This is a symlink to the latest release in the releases/ folder, so you can use it as the root public folder for your site. If you’re comfortable in Apache-config-land then you should be able to setup your VirtualHost file to point to this symlink, otherwise you can just create another symlink in your public folder that points to it. For example, if your server is setup to serve from ~/var/www/ then you could replace the www/ folder with a symlink to ~/sites/example.com/current to serve your newly deployed application instead.

Configuration

In our first step (cap deploy:setup for the short of memory), the recipe creates an empty config.php file in the shared/manifest/ folder, so you’ll need to update this with your real configuration for anything to work.

Media

Capistrano is pretty flexible, so you can create extra tasks (with various namespaces) for anything really. An example of this is the task I use for moving media/uploads from my local machine to/from the server. If you have a look at the Capfile, you’ll see a couple of tasks namespaced under :media. These do an scp upload or download from the workspace/media/ directory on your local machine to/from the shared/media/ directory in your application folder on the server. To run them, just type:

cap deploy:media:upload

or

cap deploy:media:download

You’ll want to be careful you don’t override any files when doing this.

Extras

While Capistrano is usually associated with deployment, there are a whole host of tasks it can be used to automate. The Capistrano FAQ is a good place to get started if you want to learn a little more.

I usually end up writing a few extra custom tasks for each site that do various boring things. For example, when I occasionally have to use shudder WordPress, I have a task that:

  • dumps the local database to an .sql file
  • finds-and-replaces the local URL in that dump as WordPress for some insane reason sets the URL config in the database (twice!).
  • uploads the database dump to the server
  • backs up the production database
  • imports the new dump

I’m sure there are a whole bunch of things you could use it for — I’m seeing Nick Dunn putting together a task that automatically dumps the latest changes from the DB Sync extension in about five minutes — so definitely share your tasks and perhaps we can compile a more comprehensive recipe that covers most everything you’d want to do with Symphony.

If you have any questions, shout out and I’ll do my best to help you out.

Crazy timing. It is now 10:59pm and am thinking about deploying Symphony with Capistrano. I am new to Symphony but use Capistrano for deployment of Rails and a few static sites.

This is a great writeup :D

Fantastic! I would like to propose that this gets added as an article in the Symphony docs.

Awesome! Thank you, Max.

This is a great resource, Max! Thanks for sharing your process.

This is packed full of win. Will be looking at putting this in practice on our own servers.

I’ll have to read this again. I missed the “dead simple” part. :-)

Max this is an awesome write-up. I have been playing with this a bit on my own, but you have taken it an order of magnitude further. I would also love to see as way to run db sync and deployment as well. That’s my biggest pain point with symphony right now with a couple of decent sized sites that I have built.

Question: Is there a GUI that can do this for me? If yes I’ll agree with the dead simple part. Otherwise this designer is going to look elsewhere. :D

I got everything deploying nicely however I can’t seem to figure out how to get the domain pointing to the current directory/shared config file.

For example I have Symphony deployed to example.com/current and config.php in example.com/shared/manifest/config.php, but when I go to example.com I just see the apache directory listing rather than a website.

Can anyone help me out? Presumably I need some htaccess magic or something.

What do you see in the directory listing? current/ shared/ releases/? Does the site serve properly from example.com/current/ ?

Hmm, nice on Max! I’m a bit of a fan of Fabric over Cap - simply as I am more familiar with it. I might post my fab deploy scripts as well if peeps are interested? FTP FTL :)

Yeah I see the directory listing just like that, and the /current folder serves the site perfectly. I just need to link the top domain straight to that /current folder somehow? And read the shared config file aswell.

@alilm: Cool, then everything is working as expected. Are you on a shared host or can you edit the Apache config? If you can edit your virtual hosts, the simplest to do is change them so that Apache serves example.com/current as the public folder for example.com.

If you’re you can’t edit the virtual host config, then what I’d do is (as mentioned in the main write-up), change your deployment to point to a location outside your public folder, say ~/sites/example.com and then delete your current public folder (the one that you’re currently deploying to) and create a symbolic link with the same name as that public folder that points to ~/sites/example.com/current.

@greenplasticine: Definitely post your Fab deploy scripts! Always good to have more than one option (plus then I can steal your ideas).

@max cool - will do, I’ll pop em up on github & post the link

As always good to see someone has done the hard work for me :) Been looking at different deployment strategies for a Symphony project, Capistrano being one of them. Anyone else used this much yet? Has there been any more tips & tricks gathered from experience since this was posted 5 months ago?

@froded: Can’t say for anyone else, but I can confirm it’s still working perfectly for me. I’ve just used it to pretty easily migrate a whole number of sites from one server to another.

Create an account or sign in to comment.

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details