StompBox : A Deployer for TorqueBox
StompBox is a simple Sinatra app that can be used to manage deployments on TorqueBox by accepting commit notifications from GitHub. It provides a user interface for managing one-click deployment and undeployment of your github repositories to TorqueBox for specific branches and commit points.
StompBox is useful for testing and development environments where your code is changing frequently and you want to quickly deploy working branches and staging instances. It integrates with your GitHub repositories to enable extremely quick and simple app deployment of any Rack-based application. And it does all this on top of the industrial-strength TorqueBox platform, automatically providing your application with enterprise-level functionality such as messaging, scheduling, tasks, clustering and more.
If you don't already have a TorqueBox instance installed, you should do that first. Head on over to the TorqueBox web site and follow the detailed instructions for downloading, installing, configuring and running TorqueBox. Don't worry - it's easy.
StompBox hasn't been tested on Windows and may not work in that environment. However, if you are running a Unix-y system such as Fedora or Mac OSX, then you should be fine.
Once you've installed TorqueBox, clone the StompBox repository, install the gems, and deploy it to your running TorqueBox instance.
$ git clone email@example.com:lance/stompbox.git Cloning into stompbox... remote: Counting objects: 187, done. remote: Compressing objects: 100% (168/168), done. remote: Total 187 (delta 108), reused 0 (delta 0) Receiving objects: 100% (187/187), 22.96 KiB, done. Resolving deltas: 100% (108/108), done. $ cd stompbox && bundle install <output clipped for brevity - you should see this at the end> Your bundle is complete! It was installed into /path/to/gem/home $ rake torquebox:deploy
Configuration options are found in config/torquebox.yml. Here are some things you'll want to pay attention to.
DATABASE_URL Provide a URI for connecting to your database. By convention, StompBox uses a database called "stompbox", but you can change this to whatever you want as long as it is supported by DataMapper. Be sure the user specified in the connection URI has appropriate privileges for executing DDL on your database. When the app starts for the first time, the tables will be created and it will fail if your user doesn't have the proper permissions.
AUTO_MIGRATE The first time you run StompBox, you'll want to have this on so that your database is automagically created. After that, it's most efficient to just unset this option by commenting it out.
DEPLOYMENTS When you deploy an application using StompBox, it clones the git repository into this directory. Make sure that your TorqueBox instance is running as a user with enough privileges to write to this directory.
REQUIRE_AUTHENTICATION To turn authentication on, set this to any non-nil value. StompBox uses the built-in JAAS authentication provided by TorqueBox and JBossAS. See the Authentication section below for more information.
API_KEY This should be set to something unguessable like an SHA1 hash. You can generate these any number of ways.
Here's one one way to generate a key.
$ echo "Now is the winter of our discontent made glorious summer by this son of York" | openssl sha1 (stdin)= e4ba3556d1d059e2eadca9488b093d6685657e00
StompBox uses the built-in JAAS authentication provided by JBoss and exposed via TorqueBox. If this is a development system (it probably should be), the simplest way to set usernames and passwords is to use the builtin rake task.
$ rake torquebox:auth:adduser username:password
Be sure to set REQUIRE_AUTHENTICATION in config/torquebox.yml as well. Voilá, authentication is enabled.
TorqueBox (and subsequently StompBox) can also authenticate with any other realm you have configured in your JBossAS. If you have configured JAAS settings in your TorqueBox instance, you may authenticate against them by supplying the authentication realm in config/torquebox.yml as shown.
auth: default: domain: my-configured-jaas-realm
Start by telling StompBox what repositories and branches you want to track.
Once you've got everything configured and deployed, you can start by telling
StompBox what repositories and branches you want to track. Then, from
GitHub, browse to the repository admin screen for one of the
repositories you specified in
config/stompbox.yml. Select "Service Hooks" ->
"Post Receive URLs" and enter your StompBox URL plus your api_key (you
configured it didn't you?). It should look something like this.
After you save your settings, testing the service hook should send a POST request to your StompBox. Play around.
This project is very immature and there are many features which are outstanding (such as any real authentication). You should not use it in a production environment. It is currently used for research, development and testing only.
This software is distributed under an MIT software license.