# 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](http://cl.ly/Qt3c).

## 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_USER`: User for the HTTP Basic Authentication (e.g: `izanami`).
* `IZANAMI_PASSWORD`: Password for the HTTP Basic Authentication (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:

    $ IZANAMI_USER=izanami IZANAMI_PASSWORD=izanami 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:

```ruby
# 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](https://github.com/ddollar/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](http://en.wikipedia.org/wiki/Izanami).

## 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