spawn your own node.js clouds, on your own hardware
haibu is the open-source node.js project for spawning and managing several node.js applications on a single server. It's an integral part of Nodejitsu's production stack and is fully supported by a dedicated team of core node.js developers.
haibu (which is Japanese for "hive") transforms node.js applications (using a Carapace) into "drones". This approach allows haibu to directly interact with node.js applications and add all sorts of additional functionality. haibu also contains a plugin system, so you can easily add even more functionality without needing to dive too far into the codebase.
haibu builds on this concept of "drones" and exposes a robust and granular API for interacting with your node.js applications. At a low level, haibu's API is exposed as a RESTFul HTTP webservice. Any system that supports basic HTTP requests can communicate with a haibu server. If you are working in Node.js, haibu comes with a high-level Node.js API client.
haibu doesn't discriminate. If your environment supports node.js, you can install haibu and start up your own node.js cloud. This makes haibu an ideal tool for both development purposes and production usage since you can seamlessly setup haibu on your local machine, on utility computing providers (such as Amazon EC2 or Rackspace), on dedicated servers, or even on a mobile phone!
haibu consists of 3 main applications, while only 2 of those are required to run your own cloud.
haibu includes a load balancer that can manage domain filtering and drone load balancing for you.
The haibu-balancer application will spawn up a load-balancer for your haibu installation.
This is entirely optional and not all deployments will want to use it.
haibu-server is haibu's main server and drone management application.
This application is used to manage all of the drones that are active on a particular install as well as track installed apps.
haibu is the main application used for interaction with a running haibu server.
This application will help administration of drones and applications.
[sudo] npm install haibu -g
haibu's documentation is still very much a work in progress. We'll be actively updating the documentation in the upcoming weeks to make it easier to get acclimated with haibu. Aside from the overview provided in this README.md file, haibu uses docco and literate style programming to provide comprehensive source code documentation. Check out /docs/haibu.html for more information.
[sudo] node bin/haibu-server
(...)
haibu started @ 127.0.0.1 on port 9002 as api-server
Now that there is a haibu server running, we can begin to interact with it's API.
##Starting an application using the haibu CLI
The haibu CLI allows for easy deployments into haibu with configuration files. A configuration file may be specified or the default '.haibuconf' file will be used. Haibu's CLI will recurse the directory path looking for the config file and prepopulate values for commands for you.
This is what a .haibuconf file may look like:
{
"address": "127.0.0.1",
"port": 9002
}The address and port should correspond to our haibu server's API endpoint. The API port is displayed in haibu-servers startup and defaults to port 9002.
Once we are in a directory with a package.json we want to use to deploy our script we can let the config file take care of communications to haibu for us:
haibu start
##Starting an application using the haibu Client (From: /examples/hello-spawn.js)
Allows you to call haibu programmatically from inside your node.js scripts.
var eyes = require('eyes'),
haibu = require('haibu');
// Create a new client for communicating with the haibu server
var client = new haibu.drone.Client({
host: 'localhost',
port: 9002
});
// A basic package.json for a node.js application on haibu
var app = {
"user": "marak",
"name": "test",
"domain": "devjitsu.com",
"repository": {
"type": "git",
"url": "https://github.com/Marak/hellonode.git",
},
"scripts": {
"start": "server.js"
}
};
// Attempt to start up a new application
client.start(app, function (err, result) {
if (err) {
console.log('Error spawning app: ' + app.name);
return eyes.inspect(err);
}
console.log('Successfully spawned app:');
eyes.inspect(result);
});
client.start(app, function (err, result) {
eyes.inspect(err);
eyes.inspect(result);
});cd path/to/your/app
tar -cz | curl -sSNT- localhost:9002/deploy/username/appname
# or, like this:
tar -czf app.tgz .
curl -sSNT app.tgz localhost:9002/deploy/username/appname
NOTE: you will need to invoke
tar -czf app.tgz .inside your app's directory else it will add directories inside the tarball that will confuse haibu. haibu only accepts gzip format.
or, programmatically:
var request = require('request')
, fs = require('fs');
fs.createReadStream(tarball)
.pipe(request.put({url: 'http://localhost:9002/deploy/username/appname'}, function (err, res, body) {
var result = JSON.parse(body) //app information
})
Once your node.js application has been started on haibu you're going to want to access it. haibu-balancer will load balance multiple instances of your application using node-http-proxy based on the domain property supplied in the package.json sent to each start request. Starting haibu-balancer is very simple:
sudo haibu-balancer
(...)
haibu started @ 127.0.0.1 on port 80 as balancer
Lets look at the sample data we sent to the haibu-server in the above example
{
"user": "marak",
"name": "test",
"domain": "devjitsu.com",
"repository": {
"type": "git",
"url": "https://github.com/Marak/hellonode.git"
},
"scripts": {
"start": "server.js"
}
}As you can see, the domain property is set to devjitsu.com. This means that incoming HTTP requests which have their HOST header set to devjitsu.com will be round-robin load-balanced across all instances of your application managed by haibu. If you're testing locally you can modify your /etc/hosts file for devjitsu.com and see your applications running in your local development environment.
If you need to integrate non-node.js systems with haibu, you can use haibu's RESTful JSON API. We recommend using haibu's native Node.js Client, but if you need to integrate with none-node.js systems this is not always a viable option.
Starting an application through the webservice
POST http://127.0.0.1:9002/drones/test/start
...
{
"start": {
"user": "marak",
"name": "test",
"domain": "devjitsu.com",
"repository": {
"type": "git",
"url": "https://github.com/Marak/hellonode.git"
},
"scripts": {
"start": "server.js"
}
}
}
Response
HTTP/1.1 200 OK
Date: Thu, 05 May 2011 18:15:36 GMT
Server: journey/0.4.0
Content-Type: application/json
Content-Length: 353
Connection: close
...
{
drone: {
uid: 'gbE3',
ctime: 1304619335818,
pid: 7903,
foreverPid: 7195,
logFile: '/Users/Charlie/.forever/gbE3.log',
options: [ '/Users/Charlie/Nodejitsu/haibu/local/marak/test/hellonode/server.js', '127.0.0.1', 8001 ],
file: '/Users/Charlie/Nodejitsu/haibu/bin/carapace',
pidFile: '/Users/Charlie/.forever/pids/gbE3.pid',
port: 8001,
host: '127.0.0.1'
}
}
Stopping an application through the webservice
POST http://127.0.0.1:9002/drones/test/stop
...
{
"stop": {
"name": "test"
}
}
response
HTTP/1.1 200 OK
Date: Thu, 05 May 2011 18:16:22 GMT
Server: journey/0.4.0
Connection: close
Transfer-Encoding: chunked
##Package.json settings
Haibu uses a package.json format extension in order to determine what to deploy. Also, haibu is a pull based server; this means that it will pull files from outside of the server in order to deploy instead of using uploading directly into the process.
###Name
The name attribute is required and will represent the name of the application being deployed.
{
"name": "app-name"
}###User
The user attribute is required and will represent the user who started up a drone.
{
"user": "myusername"
}###Repositories
This type of repository will pull a git repository into haibu and deploy its contents.
{
"repository": {
"type": "git",
"url": "http://path/to/git/server"
}
}This type of repository will pull a directory relative to the haibu-server and deploy its contents.
{
"repository": {
"type": "local",
"directory": "/path/to/application"
}
}This type of repository will pull a remote archive relative to the haibu-server and deploy its contents.
{
"repository": {
"type": "tar",
"url": "http://path/to/archive.tar"
}
}This type of repository will pull a remote archive relative to the haibu-server and deploy its contents.
{
"repository": {
"type": "zip",
"url": "http://path/to/archive.zip"
}
}This type of repository will install a npm package as application. The package will be available as directory under its name and the scripts will be installed in the .bin directory.
So scripts.start should have one of both as relative directory:
"scripts": {
"start": ".bin/server.js"
}or:
"scripts": {
"start": "name of npm package/server.js"
}{
"repository": {
"type": "npm",
"package": "name of npm package"
}
}All of the haibu tests are written in vows, and cover all of the use cases described above.
sudo bin/test --spec
If you copy and paste the above link, the test suite will attempt to connect to Rackspace for some of the remote file tests. You don't need to run these tests or use Rackspace to get started. We'll be improving our test runner soon to help make this process a bit more intuitive.
jitsu is intended to work with the full production stack at Nodejitsu and should not be used with haibu.
Many browsers will submit multiple requests beyond a simple html page, favicons are a likely culprit.
No, haibu-balancer is a completely optional part of haibu and does not need to be run.