# TorqueBox BackStage #

BackStage is a Sinatra application that when deployed into a TorqueBox 
server gives you visibility into the apps, queues, topics, message 
processors, jobs, and services, allowing you to browse settings and stats, 
and exposes some actions to allow you to change the operational state of 
the components:

* pause/resume queues and topics
* stop/start message processors, services, and jobs
* execute debug ruby code inside a runtime pool
* view stats on all of the above 

In addition, BackStage allows you to browse messages on a queue, and hides
some of the underlying complexity of how topics are implemented in HornetQ.

It basically acts as an friendly overlay for JMX, so is very easy to 
extend if there is more data you want to see. The data/actions that are
available from BackStage are also available from `/jmx-console` (with
the exception of queue message browsing), but are more accessible in
BackStage.

*Note:* The master branch now only supports TorqueBox 2.x. If you need
BackStage for TorqueBox 1.x, install version 0.5.4 of the gem, or use
the tag `v0.5.4` from this repo.

## Installation ##

BackStage can either be installed and deployed as a gem, or deployed from the
application source. 

### As A Gem ###

A version of the gem that supports TorqueBox 2.0.0.beta2 is currently
available as a beta itself. You can install it via:

    jruby -S gem install torquebox-backstage --pre
    
Deploy backstage using the `backstage` command. You can deploy with security
disabled: `jruby -S backstage deploy`
Or enable security by providing a username/password pair: `jruby -S backstage deploy --secure=username:password`

If you are deploying to the torquebox-server gem, you'll need to provide the
`$TORQUEBOX_HOME` environment var. You can obtain that from the `torquebox` 
command and set it like so:

    TORQUEBOX_HOME=`torquebox env torquebox_home` backstage deploy

### From Source ###

*Note:* unless you are doing development on BackStage, the recommended
install method is to build and install the gem (see above).

Clone the [git repo](https://github.com/torquebox/backstage),
then run bundler to install the needed gems (listed in the 
[Gemfile](https://github.com/torquebox/backstage/blob/master/Gemfile)):

    jruby -S gem install bundler # if you haven't done so already
    jruby -S bundle install
    
Once that's done, you can either deploy a deployment descriptor pointing at 
the checked out repo:

    jruby -S rake torquebox:deploy
    
or archive and deploy it as a .knob (zipfile):

    jruby -S rake torquebox:deploy:archive
    
By default, BackStage is deployed to the `/backstage` context (see the `context:` 
setting in `torquebox.yml`).

## API ##

BackStage also provides a RESTful API that allows you to access almost any of the 
data or actions of the web UI (browsing messages via the API is not yet available).
The API provides a top level entry point at `/api` that returns a list of collection 
urls. The data is returned as JSON, and you must either  pass `format=json` as a
query parameter, or set the `Accept:` header to `application/json`. `/api` always
returns JSON, no matter what `Accept:` header or format param you use, and all of 
the urls returned in the JSON include the `format=json` parameter. 

### Example ###

First, we retrieve the API entry point:

    curl http://localhost:8080/backstage/api 

Returns:

    {
      "collections":{
        "apps":"http://localhost:8080/backstage/apps?format=json",
        "queues":"http://localhost:8080/backstage/queues?format=json",
        "topics":"http://localhost:8080/backstage/topics?format=json",
        "message_processors":"http://localhost:8080/backstage/message_processors?format=json",
        "jobs":"http://localhost:8080/backstage/jobs?format=json",
        "services":"http://localhost:8080/backstage/services?format=json",
        "pools":"http://localhost:8080/backstage/pools?format=json",
        "logs":"http://localhost:8080/backstage/logs?format=json"
      }
    }

Then, we'll use the url for services to retrieve the service index:

    curl http://localhost:8080/backstage/services?format=json

Returns:
    
    [
      {
        "resource":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=?format=json",
        "name":"AService",
        "app":"http://localhost:8080/backstage/app/dG9ycXVlYm94LmFwcHM6YXBwPWtpdGNoZW4tc2luay50cnE=?format=json",
        "app_name":"kitchen-sink",
        "status":"Started",
        "actions":{
          "stop":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/stop?format=json"
        }
      }
    ]

Each index entry contains the full contents of the entry, along with URL
to access the resource itself. URLs to associated resources are included as
well (the app in this case).

If a resource has actions that can be performed on it, they will appear in
the results under `actions`. Action urls must be called via POST, and 
return the JSON encoded resource:

    curl -X POST http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/stop?format=json
    
Returns:

    {
      "resource":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=?format=json",
      "name":"AService",
      "app":"http://localhost:8080/backstage/app/dG9ycXVlYm94LmFwcHM6YXBwPWtpdGNoZW4tc2luay50cnE=?format=json",
      "app_name":"kitchen-sink",
      "status":"Stopped",
      "actions":{
        "start'":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/start'?format=json"
      }
    }

## Contributing ##

Bug reports, feature requests, and patches are always welcome! See
http://torquebox.org/community/ on how to get in touch with the TorqueBox
crew.

## License ##

Copyright 2011 Red Hat, Inc.

Licensed under the Apache Software License version 2. See 
http://www.apache.org/licenses/LICENSE-2.0 for details.