kibana-rack

Embed Kibana as a Rack application.

Kibana is an open source (Apache Licensed), browser based analytics and search interface to Logstash and other timestamped data sets stored in ElasticSearch. With those in place Kibana is a snap to setup and start using (seriously). Kibana strives to be easy to get started with, while also being flexible and powerful

kibana-rack tracks the latest version of Kibana (currently 3.1.1) and embeds it directly in your application, along with a proxy for the Elasticsearch API endpoints that Kibana needs.

Kibana dashboards can be created using ERB-processed JSON files in the directory specified by your kibana-rack configuration.

Requirements

Ruby 2.1+ (kibana-rack is developed and tested with Ruby 2.1.2)

Kibana requirements (also from the Kibana readme)

Elasticsearch 0.90.9 or above
A modern web browser. The latest version of Chrome, Safari and Firefox have all been tested to work. IE9 and greater should work. IE8 does not.
A webserver. No extensions are required, as long as it can serve plain html it will work
A browser reachable Elasticsearch server. Port 9200 must be open, or a proxy configured to allow access to it. (kibana-rack takes care of this for you!)

Installation

Add this line to your application's Gemfile:

gem 'kibana-rack', '~> 0.1.0'

And then execute:

$ bundle

Rails

Note: kibana-rails is coming soon!

Create an initializer at config/initializers/kibana.rb to configure kibana-rack:

Kibana.configure do |config|
  config.elasticsearch_host = 'localhost'
  config.elasticsearch_port = 9200
  config.kibana_dashboards_path = Rails.root.join('app/kibana')
  config.kibana_default_route = '/dashboard/file/default.json'
  config.kibana_index = 'kibana-int'
end

Modify config/routes.rb:

Rails.application.routes.draw do
  mount Kibana::Rack::Web => '/kibana'
end

Sinatra and other Rack applications

Configure kibana-rack:

Kibana.configure do |config|
  config.elasticsearch_host = 'localhost'
  config.elasticsearch_port = 9200
  config.kibana_dashboards_path = File.expand_path('../path/to/dashboards', __FILE__)
  config.kibana_default_route = '/dashboard/file/default.json'
  config.kibana_index = 'kibana-int'
end

Mount kibana-rack with Rack::Builder:

class MyRackApplication < Sinatra::Base
  ...
end

app = Rack::Builder.new do
  map('/kibana') { use Kibana::Rack::Web }
  run MyRackApplication
end

run app

Usage

See the Kibana documentation for information on how to use Kibana.

Configuration

kibana-rack is configured by default to serve the dashboards that come in the gem (see the dashboards directory), and proxy to Elasticsearch on localhost:9200. It is recommended that you maintain your own dashboards directory inside of the application that kibana-rack is mounted in. Production deployments will also most likely need to configure the address of Elasticsearch.

The following settings are available as accessors on the object yielded to from Kibana.configure:

Kibana.configure do |config|
  config.elasticsearch_host = '10.0.8.9'
  ...
end

Name	Description
`elasticsearch_host`	The host of the Elasticsearch instance to proxy to. Default: `localhost`
`elasticsearch_port`	The port of the Elasticsearch instance to proxy to. Default: `9200`
`kibana_dashboards_path`	The directory to look for dashboards in. Default: `dashboards` directory inside of kibana-rack
`kibana_default_route`	The default path that Kibana will load. Default: `/dashboard/file/default.json`
`kibana_index`	The name of the Elasticsearch index Kibana will use for internal storage. Default: `kibana-int`

Securing the `/kibana` endpoint

Kibana is very useful to have in production for things like searching logs and exploring Elasticsearch indexes. When using kibana-rack in a production environment, be sure to secure it from unauthorized access.

Devise

In config/routes.rb:

authenticate :user do
  mount Kibana::Rack::Web => '/kibana'
end

Or authenticate only if User#admin? returns true for current_user:

authenticate :user, ->(user) { user.admin? } do
  mount Kibana::Rack::Web => '/kibana'
end

Rack with HTTP basic authentication

require 'kibana/rack'

map '/kibana' do
  use Rack::Auth::Basic, 'Restricted Access' do |username, password|
    username == 'kibana' && password == 'kibana'
  end

  run Kibana::Rack::Web
end

Documentation

See the examples directory for installation and configuration examples.

See the YARD documentation for the latest API documentation.

Generate local documentation with YARD (output to the doc directory):

$ bundle exec rake yard

Support

Development and testing

kibana-rack follows the Ruby Style Guide for style conventions, with a few exceptions. See .rubocop.yml for the details.

Run linters (RuboCop and Inch):

$ bundle exec rake lint

Run tests:

$ bundle exec rake spec

Install pre-commit hooks for overcommit (configuration is in .overcommit.yml):

$ gem install overcommit
$ overcommit --install

Security

Installation

kibana-rack is cryptographically signed. To be sure the gem you install hasn't been tampered with, add my public key (if you haven't already) as a trusted certificate:

$ gem cert --add <(curl -Ls https://raw.github.com/tabolario/kibana-rack/master/tabolario.pem)

Installing the gem with the MediumSecurity trust profile will verify all signed gems, but allow the installation of unsigned dependencies:

$ gem install kibana-rack -P MediumSecurity

You can also set the trust file for Bundler:

$ bundle --trust-policy MediumSecurity

Using the MediumSecurity policy is often necessary because not all of your dependencies may not be signed, so HighSecurity is not an option.

Reporting Security Issues

If you have discovered an issue with kibana-rack of a sensitive nature that could compromise the security of kibana-rack users, please report it securely by sending a GPG-encrypted message instead of filing an issue on GitHub. Please use the following key and send your report to [email protected].

https://raw.github.com/tabolario/kibana-rack/tabolario.gpg

The fingerprint of the key should be:

6EED 2359 968F 7734 06A4 AB56 D90E 487A 60F1 0579

Contributing

See CONTRIBUTING.md for full information on how to contribute to kibana-rack.

Release process

kibana-rack follows Semver 2.0.0 for release versioning. The version number components X.Y.Z have the following meanings:

X for Major releases that may contain backwards-incompatible changes.
Y for Minor releases that may contain features, bug fixes, and backwards-compatible changes.
Z for Patch releases that only contain bug fixes and trivial changes.

Pre-release versions like X.Y.Z.alpha.0 and X.Y.Z.beta.1 will be made before Major, and Minor versions. Pre-release versions are well-tested, but not as thoroughly as the versions that they precede.

Whenever a new version is made, it will be tagged as a release on GitHub Releases and pushed to RubyGems. Entries in CHANGELOG.md will be made incrementally up to the release. An announcement will also be made on Twitter.

When a new Major version is made, a corresponding branch will be created named X-0-0 for further Minor and Patch releases on that version.

Todo

See the issue tracker for the current list of todos.

License

kibana-rack


Author	Tony Burns <[email protected]>
Copyright	Copyright (c) 2014 Tony Burns
License	MIT License

MIT License

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Kibana


Copyright	Copyright 2012-2013 Elasticsearch BV
License	Apache License, Version 2.0

kibana-rack

Requirements

Kibana requirements (also from the Kibana readme)

Installation

Rails

Sinatra and other Rack applications

Usage

Configuration

Securing the /kibana endpoint

Devise

Rack with HTTP basic authentication

Documentation

Support

Development and testing

Security

Installation

Reporting Security Issues

Contributing

Release process

Todo

License

kibana-rack

Kibana

Securing the `/kibana` endpoint