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 todevelopment
).IZANAMI_PORT
: Web app port (defaults to4567
).IZANAMI_AUTH
: Check if the app should use the built in basic auth module. Passdisable
ordisabled
to skip it (isenabled
by default).IZANAMI_USER
: User for the HTTP Basic Authentication, ifIZANAMI_AUTH
is enabled (e.g:izanami
).IZANAMI_PASSWORD
: Password for the HTTP Basic Authentication, ifIZANAMI_AUTH
is enabled (e.g:$3cr3t
).IZANAMI_REDIS_URL
: Redis configuration in URL format (defaults toredis://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
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request