apiary
spawn multi-system multi-user Node.JS clouds, on your own hardware and/or with 3rd party virtual servers
What is apiary?
Apiary is the open-source project that uses Node.JS and haibu for spawning and managing several multi-user Node.JS applications on multiple (physical or virtual) servers.
How does it work?
apiary
(which is English for 'beehive area') creates per (virtual) system per user application hives (or haibu, which is Japanese for "hive"). By using haibu, Node.JS applications are transformed into "drones". This approach allows apiary
and haibu to directly interact with Node.JS applications and add all sorts of additional functionality.
apiary
builds on the concept of "drones" used in haibu and exposes a robust and granular API for interacting with your and others Node.JS applications acros multiple (virtual) systems. At a low level, the API of apiary
is exposed as a RESTFul HTTP webservice. Any system that supports basic HTTP requests can communicate with apiary
System Environment Controllers and installed applications. If you are working in Node.JS, apiary
comes with a high-level Node.JS User Environment Controller javascript API client module.
Where can I run apiary?
apiary
doesn't discriminate. If your environment supports Node.JS, you can install apiary
and start up your own multi-system multi-user Node.JS cloud. This makes apiary
an ideal tool for both development purposes and production usage since you can seamlessly setup apiary
on your local machine, on utility computing providers (such as Amazon EC2 or Rackspace) or on dedicated servers!
Installation
Apiary is available in the NPM repository and can be installed globally with:
sudo npm install apiary -g
An overview of using Apiary
All CLI interaction has to be done as a user with root rights. On most Linux systems a user command can be 'upgraded' with root rights by using sudo... With the -h flag help can be requested on all CLi commands:
[sudo] apiary -h
[sander@development examples]$ sudo ../bin/apiary -h
info:
___ .______ __ ___ .______ ____ ____
/ \ | _ \ | | / \ | _ \ \ \ / /
/ ^ \ | |_) | | | / ^ \ | |_) | \ \/ /
/ /_\ \ | ___/ | | / /_\ \ | / \_ _/
/ _____ \ | | | | / _____ \ | |\ \-. | |
/__/ \__\ | _| |__| /__/ \__\ | _| `.__| |__|
info: Running Apiary CLI version 0.0.2
info: Using CLI config file /home/sander/.apiaryconf
info: No Apiary System running!
info: Deployment script is /home/sander/Development/apiary/examples/deploy.json
info: Current application user:
info:
info: apiary
info: CLI interface to manage an Apiary System.
info: Please refer to documentation of commands using `-h` or `--help`.
info:
info: commands
info: apiary start
info: apiary stop
info: apiary status
info: apiary clean
info: apiary apps
info: apiary config
info:
info: flags
info: -s --silent Do not log to console
info: -d --debug Log extended error messages
info: -c --conf Configuration filename to use (default: .apiaryconf)
info:
[sander@development examples]$
apiary
environment
Starting up an To start an Apiary system:
[sudo] apiary start
[sander@development examples]$ sudo ../bin/apiary start
info:
___ .______ __ ___ .______ ____ ____
/ \ | _ \ | | / \ | _ \ \ \ / /
/ ^ \ | |_) | | | / ^ \ | |_) | \ \/ /
/ /_\ \ | ___/ | | / /_\ \ | / \_ _/
/ _____ \ | | | | / _____ \ | |\ \-. | |
/__/ \__\ | _| |__| /__/ \__\ | _| `.__| |__|
info: Running Apiary CLI version 0.0.2
info: Using CLI config file /home/sander/.apiaryconf
info: No Apiary System running!
info: Deployment script is /home/sander/Development/apiary/examples/deploy.json
info: Current application user:
info:
info: Starting the Apiary system!
info:
info: The Apiary system is started as daemon!
info:
[sander@development examples]$
to stop a running Apairy system:
[sudo] apiary stop
User configuration
To add a system user as an Apiary user:
[sudo] apiary users add apiary_user_1
To remove an Apiary user:
[sudo] apiary users remove apiary_user_1
To list all users configured on the Apiary system:
[sudo] apiary users list
To stop apps from, and remove an Apiary user and also clean the users filesystem of Apiary directories and files:
[sudo] apiary users clean apiary_user_1
App configuration
To start an application described by examples/deploy.json:
[sudo] apiary -f examples/deploy.json -u apiary_user_1 apps start
To stop an application:
[sudo] apiary -f examples/deploy.json -u apiary_user_1 apps stop
To list all running applications:
[sudo] apiary apps list
To list all running applications for a specific user:
[sudo] apiary apps list apiary_user_1
To clean the user filesystem from all files related to a running app (and stop the app):
[sudo] apiary -u apiary_user_1 apps clean test
deploy.json attribute settings
Apiary uses a .json formated file in order to determine what to deploy.
Also, apiary
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.
A basic deploy.json for a node.js application on apiary:
User
The user attribute is optional and will represent the system user which will own the application.
If not defined then the default system user setting of the apiary
CLI will be used.
Name
The name attribute is required and will represent the name of the application being deployed.
Repositories
Five application code repository types are supported.
git
This type of repository will pull a git repository into apiary
and deploy its contents.
The branch attribute is optional!
local
This type of repository will pull a directory from the local file system into apiary
and deploy its contents.
tar
This type of repository will pull a remote tar archive into the apiary
system and deploy its contents.
zip
This type of repository will pull a remote zip archive to the apiary
system and deploy its contents.
npm
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":
or:
"scripts":
Code documentation
The code documentation of apiary
is still very much a work in progress. We'll be actively updating the documentation in the upcoming months to make it easier to contribute code to apiary
.
A first preview of the current alpha documentation can be found here!
Run Tests
All of the apiary
tests are written in vows, and cover all of the use cases described above.
the tests can be started by typing npm test
in the apiary
directory.
(To be implemented)
Open Source Projects Used
apiary
wouldn't exists weren't for the wildly productive Node.JS community producing so many high quality software.
Especially many thanks to the Nodejitsu people for writing such nice code (haibu, forever, hook.io). I learned a lot about javascript coding by just looking through their code!!
Main projects that we use as building blocks:
- async by caolan
- clip by bmeck
- colors by marak
- dnode by substack
- eventemitter2 by hij1nx
- eyes by cloudhead
- forever by indexzero
- haibu by Nodejitsu
- haibu-carapace by Nodejitsu
- hook.io by marak and others hookio
- nconf by indexzero
- optimist by substack
- and of course Node.JS!
Thanks to all developers and contributors of these projects!
Documentation License
Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License
http://creativecommons.org/licenses/by-nc-sa/3.0/
Copyright (c)2011 TTC/Sander Tolsma
Code License
Copyright (c)2011 TTC/Sander Tolsma
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.