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
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.
Capfileis the generic Capfile shared by all applications
deploy.rbhas configurations that are shared by all applications
my_application/Capfileis the Capfile that will be used for this particular application
my_application/deploy.rbincludes configuration shared by every stage of the application
my_application/production.rbfiles 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
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"
Loading the repository
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.
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:
-ccommand line option
The fastest way is probably the
.pulsar/config file inside your home
# # Inside ~/.pulsar/config # PULSAR_CONF_REPO="gh-user/pulsar-conf" # # You can use local repository for development so you don't need to push changes # every time # # PULSAR_CONF_REPO="/full/path/to/repository" # # 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.
deploy command really means running Capistrano on a certain
$ pulsar deploy my_application production
The above command will fetch the Pulsar configuration repository, run
bundle install, combine the generic
deploy.rb files with the
my_application specific ones and add specific
configuration. At last it will run
cap deploy on it.
Right now Pulsar does not support tasks other then deploy. Support for running other Capistrano tasks will come, state tuned!
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
Execute arbitrary Capistrano tasks
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 mycustom:task[argumen1,argument2] my_application staging
or via environment variables.
$ TASK_ARG1=arg1 TASK_ARG2=arg2 pulsar task mycustom:task my_application staging
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 service
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.