capistrano/documentation/getting-started/preparing-your-application/index.markdown

title	layout
Preparing Your Application	default

This will focus on preparing a Rails application, but most ideas expressed here have parallels in Python, or PHP applications

1. Commit your application to some externally available source control hosting provider.

If you are not doing already, you should host your code somewhere with a provuder such as Github, BitBucket, Codeplane, or repositoryhosting.com.

At present Capistrano v3.0.x only supports Git. It's just a matter of time until we support Subversion, Mecurial, Darcs and friends again. Please contribute if you know these tools well, we don't and don't want to force our miscomprehended notions upon anyone.

2. Move secrets out of the repository.

If you've accidentally committed state secrets to the repository, you might want to take special steps to erase them from the repository history for all time.

Ideally one should remove config/database.yml to something like config/database.yml.example, you and your team should copy the example file into place on their development machines, under Capistrano this leaves the database.yml filename unused so that we can symlink the production database configuration into place at deploy time.

The original database.yml should be added to the .gitignore (or your SCM's parallel concept of ignored files)

{% prism bash %} $ cp config/database.yml{,.example} $ echo config/database.yml >> .gitignore {% endprism %}

This should be done for any other secret files, we'll create the production version of the file when we deploy, and symlink it into place.

3. Initialize Capistrano in your application.

{% prism bash %} $ cd my-project $ cap install {% endprism %}

This will create a bunch of files, the important ones are:

{% prism bash %} ├── Capfile ├── config │   ├── deploy │   │   ├── production.rb │   │   └── staging.rb │   └── deploy.rb └── lib └── capistrano └── tasks {% endprism %}

4. Configure your server addresses in the generated files.

We'll just work with the staging environment here, so you can pretend that config/deploy/production.rb doesn't exist, for the most part that's your business.

Capistrano breaks down common tasks into a notion of roles, that is, taking a typical Rails application that we have roughly speaking three roles, web, app, and db.

It can be confusing, as the boundary of web and app servers is a bit blurry if using Passenger with Apache, which in effect embeds your app server in the web server (embeds Passenger in the Apache process itself), confusingly Passenger can also be used in modes where this isn't true, so we'll ignore that for the time being, and if you know the difference (i.e you are using nginx as your web server, and puma/unicorn, or similar for your app server, that should be fine) we can assume that they're the same, which is pretty common.

The example file generated will look something like this:

{% prism ruby %} set :stage, :staging

# Simple Role Syntax
# ==================
# Supports bulk-adding hosts to roles, the primary
# server in each group is considered to be the first
# unless any hosts have the primary property set.
role :app, %w{example.com}
role :web, %w{example.com}
role :db,  %w{example.com}

# Extended Server Syntax
# ======================
# This can be used to drop a more detailed server
# definition into the server list. The second argument
# something that quacks like a hash can be used to set
# extended properties on the server.
server 'example.com', roles: %w{web app}, my_property: :my_value

# set :rails_env, :staging

{% endprism %}

Both the simple role, and extended server syntaxes result in one or more servers for each role being defined. The app and db roles are just placeholders, if you are using the capistrano/rails-* addons (more on that later) then they have a meaning, but if you are deploying something simpler, feel free to delete them if they're meaningless to you.

The extended server syntax exists to allow the definition of arbitrary server properties; it's there incase people want to build the server list more comprehensively from something like the EC2 command line tools, and want to use the extended properties for something that makes sense in their environment.

Servers can be defined in a bunch of ways, the following shows defining two servers, one where we set the username, and another where we set the port. These host strings are parsed and expanded out in to the equivilent of the server line after the comment:

{% prism ruby %} role :all, %w{hello@world.com example.com:1234}

...is the same as doing...

server 'world.com' roles: [:web], user: 'hello' server 'example.com', roles: [:web], port: 1234 {% endprism %}

5. Set the shared information in deploy.rb.

The deploy.rb is a place where the configuration common to each environment can be specified, normally the repository URL and the user as whom to deploy are specified here.

The generated sample file starts with the following, and is followed by a few self-documenting, commented-out configuration options, feel free to play with them a little:

{% prism ruby %} set :application, 'my app name' set :repo_url, 'git@example.com:me/my_repo.git' ask :branch, proc { git rev-parse --abbrev-ref HEAD.chomp } {% endprism %}

Here we'd set the name of the application, ideally in a way that's safe for filenames on your target operating system.

Second we set the repository URL, this MUST be somewhere that the server we are deploying to can reach.

Here's how this might look in a typical example, note that we'll cover authentication in the next chapter, for now we'll assume this repository is open source, we'll take an example application from the Rails Examples and Tutorials site; there we'll find maintained a handful of typical Rails apps with typical dependencies.

The Rails application they host, which uses Devise (for authentication) and Cancan (for authorization) along side Twitter Bootstrap for assets has been forked to the Capistrano repository, but you can find the (unchanged) original here.

{% prism ruby %} set :application, 'rails3-bootstrap-devise-cancan-demo' set :repo_url, 'https://github.com/capistrano/rails3-bootstrap-devise-cancan' set :branch, 'master' {% endprism %}

I've simplified the :branch variable to simply be a set variable, not a question prompt, as this repository only has a master branch.

Roundup

At this point Capistrano knows where to find our servers, and where to find our code.

We've not covered how we authorise our servers to check out our code (there are three pretty good ways of doing that with Git), nor have we determined how to authorise Capistrano on our servers yet.