Skip to content

Commit

Permalink
Switch to markdown format for README
Browse files Browse the repository at this point in the history
  • Loading branch information
@woods
woods committed Nov 12, 2014
1 parent c92d9ca commit ad03580
Showing 1 changed file with 73 additions and 70 deletions.
143 changes: 73 additions & 70 deletions README.rdoc → README.md
View file
@@ -1,9 +1,9 @@
= capistrano-helpers
# capistrano-helpers

A set of optional extensions to capistrano to make common tasks easier and
reduce redundancy across your deployments.

== Usage
## Usage

In your capistrano deploy recipe, simply require the helpers that contain the
functionality that you would like to add to your recipe. In most cases this
Expand All @@ -12,120 +12,123 @@ time during deployment.

Here's an example config/deploy.rb that uses a few helpers:

require 'capistrano-helpers/passenger' # Support for Apache passenger
require 'capistrano-helpers/specs' # Check specs before deploying
require 'capistrano-helpers/version' # Record the version number after deploying
require 'capistrano-helpers/campfire' # Post deploy info to campfire

# The name of the application.
set :application, "myapp"

# The source code management software to use.
set :scm, "git"

# Location of the source code.
set :repository, "git@github.com:mycompany/myapp.git"
require 'capistrano-helpers/passenger' # Support for Apache passenger
require 'capistrano-helpers/specs' # Check specs before deploying
require 'capistrano-helpers/version' # Record the version number after deploying
require 'capistrano-helpers/campfire' # Post deploy info to campfire
# The name of the application.
set :application, "myapp"
# The source code management software to use.
set :scm, "git"
# Location of the source code.
set :repository, "git@github.com:mycompany/myapp.git"

That's it! The recipe will now also perform the actions described by the
helpers (in this case, the campfire helper also requires the tinder gem and
a config/campfire.yml file).

== Helpers
## Helpers

=== branch
### branch

Prompts the user for the particular tag/branch/commit to deploy.

=== bundler
### bundler

Automatically runs `bundle install --deployment` to install gems from your Gemfile at the appropriate time.

Automatically runs "bundle install --deployment" to install gems from your Gemfile at the appropriate time.
[Deprecated] This recipe predates bundler's direct support for capistrano. It's best to
`require 'bundler/capistrano'` in your recipe now instead of using this helper.

=== campfire
### campfire

Once the deploy is complete, this helper will post a message to the given
Campfire room stating the username, the application, the branch/tag and the
environment. E.g.:

Scott Woods finished deploying myapp v0.5.4 to staging
Scott Woods finished deploying myapp v0.5.4 to staging

By default, it will only post when the deploy is complete. If you'd also
like it to post when the deploy begins, you can add the following line
to your deploy script:

before "deploy", "deploy:post_to_campfire_before"
before "deploy", "deploy:post_to_campfire_before"

You will need to install the tinder gem to enable campfire notifications. Run
<tt>sudo gem install tinder</tt>, or add <tt>gem 'tinder'</tt> to your Gemfile.
This helper expects to find a configuration file config/campfire.yml or
~/.campfire.yml with the following format:

# Configuration for posting to campfire.
subdomain: mycompany
token: abcd1234567890
room: Chatter
# Configuration for posting to campfire.
subdomain: mycompany
token: abcd1234567890
room: Chatter

You can override the location of the configuration file by setting the
:campfire_config variable:

set :campfire_config, 'somewhere/else.yml'
set :campfire_config, 'somewhere/else.yml'

You can disable the notification for a specific deployment stage by setting
the :campfire_notifications variable to false.
E.g. in config/deploy/staging:

set :campfire_notifications, false
set :campfire_notifications, false

=== ding
### ding

Once the deploy is complete, this helper will play a 'ding' sound (Mac only).

=== features
### features

Before the app is deployed, this helper checks out the branch/tag that is
being deployed and runs all the cucumber features, ensuring that they all
pass.

=== gems
### gems

Run the gems:install rake task using sudo after deployment.

=== git
### git

Set git as the repository type, and set up remote caching to speed up
deployments.

=== growl
### growl

Once the deploy is complete, this helper will post a message to Growl stating
the application, the branch/tag and the environment. E.g.:

capistrano
capistrano

finished deploying myapp v0.5.4 to staging

finished deploying myapp v0.5.4 to staging

=== jekyll
### jekyll

Deploy a static website with [jekyll](http://jekyllrb.com/). Rebuild the site
during deployment, and override any server restarts (since it's just a static
site).

=== migrations
### migrations

Always run migrations during deployment.

=== passenger
### passenger

Overrides the default :restart task so that it's compatible with restarting
apache/passenger (aka mod_rails). Touches tmp/restart.txt.

=== php
### php

Use this helper when using capistrano to deploy a purely PHP application.

This neuters the default :restart and :finalize_updates tasks, since they
aren't typically needed for a PHP installation.

=== preflight
### preflight

Goes through a set of yes/no questions with the user before the application is
actually deployed. This provides a way to walk the user through a set of
Expand All @@ -135,19 +138,19 @@ affirmatively.
This helper expects to find the questions in a configuration file called
config/preflight.yml . The file should be in the following format:

# Questions that must be answered "yes" before a deploy is allowed to proceed.
- Does cruise control show all tests passing?
- Do the staging and production servers have the required gems installed?
- Are you prepared to run migrations on the remote server?
- Have you tagged this release?
- Have you pushed the tags to github?

# Questions that must be answered "yes" before a deploy is allowed to proceed.
- Does cruise control show all tests passing?
- Do the staging and production servers have the required gems installed?
- Are you prepared to run migrations on the remote server?
- Have you tagged this release?
- Have you pushed the tags to github?
You can override the location of the configuration file by setting the
:preflight_config variable:

set :preflight_config, 'somewhere/else.yml'
set :preflight_config, 'somewhere/else.yml'

=== shared
### shared

During deployment, this helper replaces each of the given paths with a
symbolic link that points to the same path under the "shared" directory on the
Expand All @@ -157,23 +160,23 @@ data that should persist across deployments (uploads, for example).
After requiring this helper, set the paths to be symlinked using the
:shared variable:

set :shared, %w{
public/uploads
public/downloads/huge_files
}
set :shared, %w{
public/uploads
public/downloads/huge_files
}

This will create two symbolic links on the production server:

#{release_path}/public/uploads -> #{shared_path}/public/uploads
#{release_path}/public/downloads/huge_files -> #{shared_path}/public/downloads/huge_files
#{release_path}/public/uploads -> #{shared_path}/public/uploads
#{release_path}/public/downloads/huge_files -> #{shared_path}/public/downloads/huge_files

=== skylinecms
### skylinecms

This is for the SkylineCMS gem. Skyline requires certain permissions and folders to operate,
and this helper insures they exist. Remember to run this *after* the rest of your symlinks exist
(eg. config/database.yml) and *before* anything loads the environment (eg. rake gems:install).

=== privates
### privates

This works much like the shared helper above, except the symbolic link will
point to the same path under "shared/private" on the server. This allows you
Expand All @@ -183,32 +186,32 @@ sensitive files safe, such as those that contain passwords or encryption keys.
After requiring this helper, set the paths to be symlinked using the
:privates variable:

set :privates, %w{
config/database.yml
config/session_secret.txt
}

set :privates, %w{
config/database.yml
config/session_secret.txt
}
This will create two symbolic links on the production server:

#{release_path}/config/database.yml -> #{shared_path}/private/config/database.yml
#{release_path}/config/session_secret.txt -> #{shared_path}/private/config/session_secret.txt

=== specs
#{release_path}/config/database.yml -> #{shared_path}/private/config/database.yml
#{release_path}/config/session_secret.txt -> #{shared_path}/private/config/session_secret.txt
### specs

Before the app is deployed, this helper checks out the branch/tag that is
being deployed and runs all the rspec specs, ensuring that they all pass.

=== unicorn
### unicorn

Overrides the default :restart task so that it's compatible with restarting
unicorn.

=== version
### version

Creates a VERSION file in the deployed copy that contains the name of the
branch/tag that was deployed. Useful for displaying version information in the
app itself.

== Copyright
## Copyright

Copyright (c) 2014 West Arete Computing, Inc.

0 comments on commit ad03580

Please sign in to comment.