Izanami

Opitionated web app to handle capistrano recipes.

Rationale

Izanami is a Sinatra app that tries to execute capistrano commands as a normal user. When a set of tasks is sent, Izanami forks a new process that executes that tasks as a UNIX command, and streams the output (via redis's pub/sub system) to the web app. The commands are stored in redis, with the sent tasks, an unique ID, the output of the command and the process status (pending, success or fail). All the redis keys are prefixed with a namespace called izanami.

Izanami can work with any kind of capistrano projects. To do so, it assumes that the capistrano recipes are in a separated directory. This directory is the sandbox and it MUST be a ruby project handled by bundler. Every capistrano command will be executed as:

$ pwd
/path/to/sandbox
$ bundle exec cap [tasks]

It's the admin reponsibility to set up that directory and to have all the bundler dependencies installed.

Other thing to be aware of is that Izanami doesn't handle interactive capistrano tasks. It cannot send inputs to a running command. That means that the capistrano commands need to be non interactive.

Izanami tries to be a simple interface over capistrano, not a complete replacement for the shell. It can help to handle basic tasks in a healthy system, but nothing beats the terminal when you need to solve more serious problems.

Showcase

You can see a small demo of the app here.

Dependencies

Izanami stores all the data about the commands executed inside redis. All the keys expire after a week. It also uses the redis' pub/sub feature to show the output of a running command.

Installation

You can install it by using the following command:

$ gem install izanami

Or build the gem:

$ gem build izanami.gemspec
$ gem install izanami-x.y.x.gem

Usage

Configuration

Izanami configuration is handled via environment variables:

  • RACK_ENV: App environment (e.g: development, production, test. Defaults to development).
  • IZANAMI_PORT: Web app port (defaults to 4567).
  • IZANAMI_AUTH: Check if the app should use the built in basic auth module. Pass disable or disabled to skip it (is enabled by default).
  • IZANAMI_USER: User for the HTTP Basic Authentication, if IZANAMI_AUTH is enabled (e.g: izanami).
  • IZANAMI_PASSWORD: Password for the HTTP Basic Authentication, if IZANAMI_AUTH is enabled (e.g: $3cr3t).
  • IZANAMI_REDIS_URL: Redis configuration in URL format (defaults to redis://127.0.0.1:6379/0).
  • IZANAMI_SANDBOX: Path to the directory with the capistrano recipes.
  • IZANAMI_WATCHDOG_SLEEP_TIME: The time the watchdog sleeps before update the sandbox git repository (default to 300 seconds).

Running the web app

Izanami runs with thin by default. You can start the app with:

# With HTTP Basic Authentication
$ IZANAMI_USER=izanami IZANAMI_PASSWORD=izanami IZANAMI_SANDBOX=/path/to/recipes izanami app

# Without HTTP Basic Authentication
$ IZANAMI_AUTH=disable IZANAMI_SANDBOX=/path/to/recipes izanami app

But Izanami is a simple Sinatra app, so you can run it with any ruby server that handles a config.ru file:

# simple config.ru file
require 'rack'
require 'izanami/app'

run Izanami::App

The app uses the Sinatra stream feature, so you will need a server that can handle it, as thin does.

The sandbox watchdog

The sandbox directory is a git repository, Izanami comes with a simple script that watches this repo and updates it (git pull) every 300 seconds (or any defined time period). This way, you can always have the latest version of the recipes.

To run the watchdog, simply start the watchdog:

$ IZANAMI_SANDBOX=/path/to/recipes izanami watchdog

The watchdog outputs to the standard output the result of executing git pull and the status of the command.

Tip: Using foreman

To handle the configuration of the app, it can be a good idea to use foreman.

This is an example for an .env file:

RACK_ENV=production
IZANAMI_PORT=8899
IZANAMI_USER=izanami
IZANAMI_PASSWORD=supersecretpass
IZANAMI_REDIS_URL=redis://redis.provider.com:6379/0
IZANAMI_SANDBOX=/var/recipes/
IZANAMI_WATCHDOG_SLEEP_TIME=600

And this can be a Procfile:

app: izanami app
watchdog: izanami watchdog

Also, foreman can be exported to init.d scripts an so on. Check the foreman documentation for more info.

Specs

To run the specs, it is necessary to prepare the dummy sandbox directory after the first clone of the repository.

There is a rake task to do it:

$ bundle exec rake spec:prepare

After this, you can run the specs:

$ bundle exec rake spec

About the name

Izanami is the name of the japanese goddess of both creation and death. Find out more about this at wikipedia.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request