The easy Capistrano deploy and configuration manager.
Pulsar allows you to run Capistrano tasks via a separate repository where all your deploy configurations are stored. Once you have your own repository, you can gradually add configurations and recipes so that you never have to duplicate code again.
The way Pulsar works means that you can deploy without actually having the application on your local machine (and neither have all your application dependencies installed). This lets you integrate Pulsar with nearly any deploy strategy you can think of.
Some of the benefits of using Pulsar:
- No Capistrano configurations in the application code
- No need to have the application locally to deploy
- Every recipe can be shared between all applications
- Can easily be integrated with other tools
- Write the least possible code to deploy
DISCLAIMER: Understanding Capistrano is strongly suggested before using Pulsar.
This version of Pulsar (version >= 1.0.0
) only supports Capistrano v3. If
you're looking for Capistrano v2 support you can use Pulsar version 0.3.5
but,
take care, that version is not maintained anymore.
The most useful way of installing Pulsar is as a system gem:
$ gem install pulsar
This will install the pulsar
command which will be used to for everything,
from running Capistrano to listing your configurations.
The first thing you'll need to do is to create your own configuration repo:
$ pulsar install ~/Desktop/pulsar-conf
This will create a basic starting point for building your configuration repository. As soon as you're done configuring you should consider transforming this folder to a git repository.
You can have a look at how your repository should look like by browsing the Pulsar Conf Demo.
NOTE: Pulsar only supports git.
This is an example repository configuration layout:
pulsar-conf/
|── Gemfile
├── Gemfile.lock
├── apps
│ ├── Capfile
│ ├── deploy.rb
│ └── my_application
│ ├── Capfile
│ ├── deploy.rb
│ ├── production.rb
│ └── staging.rb
└── recipes
├── generic
│ ├── maintenance_mode.rake
│ ├── notify.rake
│ └── utils.rake
├── rails
│ ├── passenger.rake
│ ├── repair_permissions.rake
│ ├── symlink_configs.rake
│ ├── unicorn.rake
│ └── whenever.rake
└── spree_1
└── symlink_assets.rake
Pulsar uses these files to build Capistrano configurations on the fly, depending
on how you invoke the pulsar
command. Since Pulsar it's basically a Capistrano
wrapper, the content of these files is plain old Capistrano syntax.
This directory contains your application configurations. You'll have one directory per application.
Capfile
is the generic Capfile shared by all applicationsdeploy.rb
has configurations that are shared by all applicationsmy_application/Capfile
is the Capfile that will be used for this particular applicationmy_application/deploy.rb
includes configuration shared by every stage of the applicationmy_application/staging.rb
andmy_application/production.rb
files include stage configurations
This directory contains your recipes. You can create any number of directories
to organize your recipes. In Capistrano v3 fashion, all the files are plain old
rake tasks (make sure to name them with the .rake
extension).
The recipes contained in this folder are always included in each stage for each application.
Another way to include your recipes is by using the Gemfile
. Many gems already
include custom recipes for Capistrano so you just need to require those. An
example with Whenever:
#
# Inside Gemfile
#
gem 'whenever'
#
# Inside some Capfile (either generic or application specific)
#
require 'whenever/capistrano'
#
# Inside some .rb configuration file (either generic or application specific)
#
set :whenever_command, "bundle exec whenever"
Once the repository is ready, you'll need to tell Pulsar where it is. The
repository location can be specified either as a full git path or a GitHub
repository path (i.e. gh-user/pulsar-conf
).
Since Pulsar requires the repository for everything, there are multiple ways to store this information so that you don't have to type it every time. You can also use local repository, which is useful while developing your deployment.
You have three possibilities:
-c
command line optionPULSAR_CONF_REPO
environment variable~/.pulsar/config
configuration file
The fastest way is probably the .pulsar/config
file inside your home
directory:
#
# Inside ~/.pulsar/config
#
PULSAR_CONF_REPO="gh-user/pulsar-conf"
#
# Also supported
#
# PULSAR_CONF_REPO="git://github.com/gh-user/pulsar-conf.git"
Pulsar will read this file and set the environment variables properly.
If you don't want to add another file to your home directory you can export the variables yourself:
#
# Inside ~/.bash_profile or ~/.zshrc
#
export PULSAR_CONF_REPO="gh-user/pulsar-conf"
After the repository is ready, running Pulsar is straightforward. You can either list your applications or build a configuration and run Capistrano on it.
Running the deploy
command really means running Capistrano on a certain
configuration.
To deploy my_application
to production
:
$ pulsar deploy my_application production
The above command will fetch the Pulsar configuration repository, run
bundle install
, combine the generic Capfile
and deploy.rb
files with the
my_application
specific ones and add specific production.rb
stage
configuration. At last it will run cap deploy
on it.
Pulsar can fetch your configuration repository and list the application and stages you can run deploys on:
$ pulsar list
This will fetch the Pulsar configuration repository and list everything that's inside, like this:
my_application: production, staging
awesome_startup: dev, production, staging
You can launch any Capistrano task via task command. You can also pass arguments in Rake style (i.e. via square brackets after task name)
$ pulsar task my_application staging mycustom:task[argumen1,argument2]
or via environment variables.
$ TASK_ARG1=arg1 TASK_ARG2=arg2 pulsar task my_application staging mycustom:task
Pulsar is easy to integrate, you just need access to the configurations repository and the ability to run a command.
Right now there are no integrations for Pulsar v1 but there are some built for the old v0.3 version that can be used as an example.
- https://gist.github.com/mtylty/5324075: a hubot script that runs Pulsar via the command line
- hubot-pulsar: a hubot plugin for integrating via Pulsar REST API
- lita-pulsar: a Lita plugin for integrating via the command line
Pulsar REST API is a service to provide a REST API for executing pulsar jobs.
Here is a real-life example of how you can integrate and simplify your Pulsar workflow.
Pulsar is funded and maintained by the Nebulab team.
We firmly believe in the power of open-source. Contact us if you like our work and you need help with your project design or development.