improve sub URI deployment / docs / other tweaks

.gitignore

@@ -1,9 +1,11 @@
-config/profiles.yaml
 .DS_Store
 log/*
 tmp/*
+pkg/*
 *~
 .#*
 webrat*
-.bundle/
-vendor/gems/*
+visage-app.gemspec
+lib/visage-app/config/profiles.yaml
+_site
+features/data/config/*/*.yaml

AUTHORS

@@ -0,0 +1,14 @@
+Visage was written by
+=====================
+Lindsay Holmwood <[email protected]>
+
+Contributors include
+--------------------
+Jeffrey Lim <[email protected]>
+Andrew Harvey <[email protected]>
+Xavier Mehrenberger <[email protected]>
+
+Inspiration given by
+--------------------
+Gareth Stokes
+Asdrubal Ibarra

Gemfile

@@ -1,6 +1,18 @@
-source :gemcutter
+#!/usr/bin/env ruby
+
+source :rubygems
 
-gem "sinatra"
 gem "haml"
+gem "tilt"
+gem "sinatra"
 gem "errand"
 gem "yajl-ruby"
+
+group :development do
+  gem "shotgun"
+  gem "rack-test"
+  gem "rspec"
+  gem "cucumber"
+  gem "webrat"
+  gem "jeweler"
+end

LICENCE

@@ -0,0 +1,27 @@
+Copyright (c) 2009-2010 Lindsay Holmwood
+
+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.
+
+Visage is distributed with Highcharts. Torstein Hønsi has kindly granted
+permission to distribute Highcharts under the GPLv2 as part of Visage.
+
+If you ever need an excellent JavaScript charting library, please consider
+purchasing a [commercial license](http://highcharts.com/license) for
+Highcharts.
+

README.md

@@ -3,7 +3,7 @@ Visage
 
 Visage is a web interface for viewing [collectd](http://collectd.org) statistics.
 
-It also provides a [JSON](http://json.org) interface onto `collectd`'s RRD data, 
+It also provides a [JSON](http://json.org) interface onto `collectd`'s RRD data,
 giving you an easy way to mash up the data.
 
 Features
@@ -14,120 +14,177 @@ Features
  * drop-down or mouse selection of timeframes (also rendered asynchronously)
  * JSON interface onto `collectd` RRDs
 
-Check out a demo at [http://visage.unstated.net/](http://visage.unstated.net).
+Here, have a graph:
 
 
+![Something I prepared earlier.](http://farm2.static.flickr.com/1020/4730994504_c8c6fc9c18_z.jpg)
+
+
+Or check out [a live demo](http://visage.unstated.net/nadia/cpu+load).
+
 Installing
 ----------
 
-Bundle dependencies:
+N.B: Visage must be deployed on a machine where `collectd` stores its stats in RRD.
 
-    $ bundle install vendor/gems/
+On Ubuntu, to install dependencies run:
 
-Amongst other things, this will pull in Errand, which requires the rrdtool
-headers to build a C extension. On Debian/Ubuntu these are in the `librrd2-dev` 
-package, and on RHEL/CentOS `rrdtool-devel`.
+    $ sudo apt-get install -y build-essential librrd-ruby ruby ruby-dev rubygems collectd
 
-Configuring
------------
+On CentOS, to install dependencies run:
 
-Config lives in several files under `config/`. 
+    $ sudo yum install -y ruby-RRDtool ruby rubygems collectd
 
- * `profiles.yaml` - groups of graphs Visage is to display
- * `plugin-colors.yaml` - colors for specific plugins/plugin instances
- * `fallback-colors.yaml` - ordered list of fallback colors
- * `init.rb` - bootstrapping code, specifies collectd's RRD directory
+If you are using Ruby Enterprise Edition, instead of installing librrd-ruby or ruby-RRDtool, run
 
-`profiles.yaml` isn't setup by default, but you can copy `profiles.yaml.sample`
-across and edit to taste. The plugins are in the format of 
-`plugin/plugin-instance`, with `plugins-instance` being optional. 
+    $ gem install librrd
 
-If you don't specify a `plugin-instance` Visage will attempt to graph all plugin
-instances under the specified `plugin`, e.g. `cpu-0` will display `cpu-idle`, 
-`cpu-interrupt`, `cpu-nice`, etc, whereas `cpu-0/cpu-wait` will only show 
-`cpu-wait`. You can also choose a specific group of plugin instances to graph,
-with something like `cpu-0/cpu-system/cpu-user/cpu-wait`.
+Then install the app with:
 
-It should be pretty easy to deduce the config format from the existing file 
-(it's simple nested key-value data).
+    $ gem install visage-app
 
-Make sure collectd's RRD directory is readable by whatever user the web server
-is running as. You can specify where collectd's rrd directory is in `init.rb`,
-with the `c['rrddir']` key.
+Running
+-------
 
-Developing
-----------
+You can try out Visage quickly with:
 
-For development: 
+    $ visage-app start
 
-    $ gem install shotgun
-    $ shotgun visage.rb
+Then paste the URL from the output into your browser.
+
+If you get a `command not found` when running the above command (RubyGems likely
+isn't on your PATH), try this instead:
+
+    $ $(dirname $(dirname $(gem which visage-app)))/bin/visage-app start
 
 Deploying
 ---------
 
-With Passenger, create an Apache vhost with the `DocumentRoot` set to the 
-`public/` directory of where you have deployed the checked out code, e.g.
+Visage can be deployed on Apache with Passenger:
+
+    $ sudo apt-get install libapache2-mod-passenger
 
+Visage can attempt to generate an Apache vhost config for use with Passenger:
+
+    $ visage-app genapache
     <VirtualHost *>
-      ServerName visage.example.org
-      ServerAdmin [email protected]
-    
-      DocumentRoot /srv/www/visage.example.org/root/public/
-    
-      <Directory "/srv/www/visage.example.org/root/public/">
+      ServerName ubuntu.localdomain
+      ServerAdmin [email protected]
+
+      DocumentRoot /home/user/.gem/ruby/1.8/gems/visage-app-0.1.0/lib/visage-app/public
+
+      <Directory "/home/user/.gem/ruby/1.8/gems/visage-app-0.1.0/lib/visage-app/public">
          Options FollowSymLinks Indexes
          AllowOverride None
          Order allow,deny
-         Allow from all 
+         Allow from all
        </Directory>
-
-       ErrorLog /srv/www/visage.example.org/log/apache_errors_log
-       CustomLog /srv/www/visage.example.org/log/apache_app_log combined
-
     </VirtualHost>
 
-This assumes you have a checkout of the code at `/srv/www/visage.example.org/root`.
+Copypasta this into your system's Apache config structure and tune to taste.
 
-If you don't want to use Apache + Passenger, you can install the `thin` or 
-`mongrel` gems and run up a web server yourself. 
+To do this on Debian/Ubuntu:
 
-Ubuntu users looking for Passenger packages should add John Ferlito's 
-[mod-passenger PPA](https://launchpad.net/~johnf-inodes/+archive/mod-passenger)
-to their apt sources.
+    $ sudo -s
+    $ visage-app genapache > /etc/apache2/sites-enabled/visage
+    $ a2dissite default
+    $ service apache2 reload
 
-Testing 
--------
+Then head to your Apache instance and Visage will be up and running.
+
+Configuring
+-----------
+
+Visage looks for two environment variables when starting up:
+
+  * `CONFIG_PATH`, an entry on the configuration file search path
+  * `RRDDIR`, the location of collectd's RRDs
+
+Visage has a configuration search path which can be used for overriding
+individual files. By default it has one entry: `$VISAGE_ROOT/lib/visage/config/`.
+You can set the `CONFIG_PATH` environment variable to add another directory to
+the config load path. This directory will be searched when loading up
+configuration files.
+
+    CONFIG_PATH=/var/local/visage-app start
+
+This is especially useful when you want to deploy + run Visage from an installed
+gem with Passenger. e.g.
+
+    <VirtualHost *:80>
+      ServerName monitoring.example.org
+      ServerAdmin [email protected]
+
+      SetEnv CONFIG_PATH /var/local/visage
+      SetEnv RRDDIR /opt/collectd/var/lib/collectd
+
+      DocumentRoot /var/lib/gems/1.8/gems/visage-app-0.3.0/lib/visage/public
+      <Directory />
+        Options FollowSymLinks
+        AllowOverride None
+      </Directory>
+
+      LogFormat "%h %l %u %t \"%r\" %>s %b" common
+      CustomLog /var/log/apache2/access.log common
+    </VirtualHost>
+
+If you are deploying to a sub URI, simply create a link to the visage-app public
+directory from within your document root:
+
+    ln -s /var/lib/gems/1.8/gems/visage-app-0.9.4/lib/visage-app/public visage
+
+Then set the RackBaseURI, but otherwise configuration is similar:
+
+    RackBaseURI /visage
+
+    SetEnv CONFIG_PATH /var/local/visage
+
+    <Directory /var/lib/gems/1.8/gems/visage-app-0.9.4/lib/visage-app/public>
+        Options FollowSymLinks Indexes
+        AllowOverride None
+        Order allow,deny
+        Allow from all
+    </Directory>
+
+Also to keep in mind when deploying with Passenger, the `CONFIG_PATH` directory
+and its files need to have the correct ownership. Passenger defaults to running
+apps as the user they are owned by, or runs them as nobody if they are owned by
+root (you can change with PassengerDefaultUser):
+
+    chown nobody:nogroup -R /var/local/visage
+
+Developing + testing
+--------------------
+
+Check out the code with:
+
+    $ git clone git://github.com/auxesis/visage.git
+
+Install the development dependencies with:
+
+    $ gem install bundler
+    $ bundle install
+
+Run all cucumber features:
+
+    $ rake cucumber
+
+And run the app with:
+
+    $ shotgun lib/visage-app/config.ru
+
+To create and install a new gem from the current source tree:
+
+    $ rake install
+
+Licencing
+---------
+
+Visage is MIT licensed.
+
+Visage is distributed with Highcharts. Torstein Hønsi has kindly granted
+permission to distribute Highcharts under the GPLv2 as part of Visage.
 
-Run all cucumber features: 
-
-    $ rake cucumber 
-
-Specific features: 
-
-    $ bin/cucumber --require features/ features/something.feature
-
-TODO
-----
-
- * create proper mootools class - DONE
- * switch to g.raphael - DONE
- * config file - DONE
- * data profiles - DONE
- * handle single plugin instance in graphing code - DONE
- * specify data url in graphing code - DONE
- * generate holders for graph/labels/time selector - DONE
- * clean up routes - DONE
- * smart colour selection (CPU-1 = CPU) - DONE
- * title attributes - DONE
- * split profiles + colors => plugins into separate files - DONE
- * fix key labels - DONE
- * axis labels (with human readable times) - DONE
- * detailed point-in-time data on hover
- * embedded html generator - DONE
- * zoom + dynamic resize - DONE
- * combine graphs from different hosts
- * comment on time periods
- * view list of comments
- * provide option to shade under graphs - DONE
- * interface to build custom graph profiles
+If you ever need an excellent JavaScript charting library, please consider
+purchasing a [commercial license](http://highcharts.com/license) for
+Highcharts.