Permalink
Browse files

some fill-paragraph action on readmes

  • Loading branch information...
1 parent afb250f commit 9a514c78912a275291b50291e2735f15e59acfc1 @jdunphy jdunphy committed Oct 28, 2010
Showing with 100 additions and 32 deletions.
  1. +22 −5 README.markdown
  2. +78 −27 lib/erlang/README.markdown
View
@@ -17,7 +17,9 @@ Beehive
make
./start_dev.sh
-This will start beehive on your local machine with the root /var/lib/beehive. If you want to use a different directory, (such as /tmp/beehive) run:
+This will start beehive on your local machine with the root
+/var/lib/beehive. If you want to use a different directory, (such as
+/tmp/beehive) run:
export BEEHIVE_HOME=/tmp/beehive
@@ -41,13 +43,28 @@ The incredibly basic architecture diagram of beehive looks like:
Storage Storage Storage
----------------------------
-The distributed routing layer, written in erlang uses [Mnesia](http://ftp.sunet.se/pub//lang/erlang/doc/apps/mnesia/index.html), the distributed database management system intelligently routes requests across the bees. The router currently can handle http requests. Because Beehive was written with the intention of being extensible it can be extensible to other protocols.
-
-It handles pending connections seamlessly and allows for streaming connections. It also keeps track of statistical data available through a web interface. The router itself has a RESTful interface for adding bees, which don't even need to sit inside the Beehive network. This can be useful for putting the router in front of a personal cluster (such as [Eucalyptus](http://www.eucalyptus.com/)) and expanding to the cloud environment (such as [EC2](http://aws.amazon.com/ec2/)) without having to change a line of code.
+The distributed routing layer, written in erlang uses
+[Mnesia](http://ftp.sunet.se/pub//lang/erlang/doc/apps/mnesia/index.html),
+the distributed database management system intelligently routes
+requests across the bees. The router currently can handle http
+requests. Because Beehive was written with the intention of being
+extensible it can be extensible to other protocols.
+
+It handles pending connections seamlessly and allows for streaming
+connections. It also keeps track of statistical data available through
+a web interface. The router itself has a RESTful interface for adding
+bees, which don't even need to sit inside the Beehive network. This
+can be useful for putting the router in front of a personal cluster
+(such as [Eucalyptus](http://www.eucalyptus.com/)) and expanding to
+the cloud environment (such as [EC2](http://aws.amazon.com/ec2/))
+without having to change a line of code.
Beehive keeps track of the available bees for the known applications.
-Beehive has an event system that allows for notifications along the system in a nonblocking manner. This way system events, statistic gathering log events can all be handled without affecting the performance of the router, which is tuned for speed.
+Beehive has an event system that allows for notifications along the
+system in a nonblocking manner. This way system events, statistic
+gathering log events can all be handled without affecting the
+performance of the router, which is tuned for speed.
---
View
@@ -9,19 +9,25 @@ To start the router:
make
./bin/start_beehive
-This will start the basic router with the default options. The default node type that gets started is the router type. You can start a node (see glossary below) with the following command. Node that the -s argument refers to a seed node. This is any node already in the mesh.
+This will start the basic router with the default options. The default
+node type that gets started is the router type. You can start a node
+(see glossary below) with the following command. Node that the -s
+argument refers to a seed node. This is any node already in the mesh.
./scripts/start_beehive.sh -t node -n bob@mymac.local -s router@mymac.local
-You also need to start some storage backends to store the squashed bees. This is easy to do with the ./scripts/start_beehive.sh script:
+You also need to start some storage backends to store the squashed
+bees. This is easy to do with the ./scripts/start_beehive.sh script:
./scripts/start_beehive.sh -t storage -s router@mymac.local
-There are many options to starting the router, for more information and options, type:
+There are many options to starting the router, for more information
+and options, type:
./scripts/start_beehive.sh -h
-To start with a list of bees, use the -i option to point to a file that looks like:
+To start with a list of bees, use the -i option to point to a file
+that looks like:
{"app1", "ec2-67-202-21-173.compute-1.amazonaws.com", 8080}.
{"app2", "ec2-174-129-54-214.compute-1.amazonaws.com", 8080}.
@@ -46,25 +52,36 @@ The user_app table stores the mappings between users and their apps
## Configuration
-There are multiple methods of configuration. If you are going to configure the router the same way every time, the recommended method is to write a configuration file and pass in the location of the configuration file at the start command with the -c option, like so:
+There are multiple methods of configuration. If you are going to
+configure the router the same way every time, the recommended method
+is to write a configuration file and pass in the location of the
+configuration file at the start command with the -c option, like so:
./scripts/start_beehive.sh -c "/path/to/configuration/file"
The configuration file must be in the following format:
{parameter_name, value}.
-These are erlang tuples, which is how beehive parses the configuration file. For samples, check out the sample configuration files here: [http://github.com/auser/beehive/tree/master/lib/erlang/config](http://github.com/auser/beehive/tree/master/lib/erlang/config).
+These are erlang tuples, which is how beehive parses the configuration
+file. For samples, check out the sample configuration files here:
+[http://github.com/auser/beehive/tree/master/lib/erlang/config](http://github.com/auser/beehive/tree/master/lib/erlang/config).
-All of the available variables that can be overridden can be overridden on the command-line as well. To see all of the available variables, run ./start_beehive.sh with the '-h' switch.
+All of the available variables that can be overridden can be
+overridden on the command-line as well. To see all of the available
+variables, run ./start_beehive.sh with the '-h' switch.
## Proxy
-The proxy can be hot-loaded with new routes simply with a RESTful interface. The name (the routing key), the endpoint host and the port of the bee need to be included. For instance:
+The proxy can be hot-loaded with new routes simply with a RESTful
+interface. The name (the routing key), the endpoint host and the port
+of the bee need to be included. For instance:
curl -i -XPOST -d"{\"app_name\":\"test\", \"host\":\"google.com\", \"port\":\"80\"}" beehive.com:8080/bees/new.json
-The parameters that must be included are the app_name (the routing key), the host and the port. You can check to make sure that they were added by calling: http://beehive.com:8080/bees.json
+The parameters that must be included are the app_name (the routing
+key), the host and the port. You can check to make sure that they were
+added by calling: http://beehive.com:8080/bees.json
These can also be added at the erlang command-line by:
@@ -73,6 +90,7 @@ These can also be added at the erlang command-line by:
bee_store:add_bee([{app_name, "streaming"}, {host, "127.0.0.1"}, {port, 5001}]).
## Apps
+
Adding an application can also be added via the RESTful interface. For example:
curl -i -XPOST -d"{\"name\":\"beehive\", \"host\":\"ec2-75-121-34-215-amazon.com\", \"port\":\"8080\"}" beehive.com:8080/apps/new.json
@@ -88,21 +106,29 @@ For instance, to terminate and restart the application in the beehive, issue a r
curl -i -XPOST http://beehive.com:8080/apps/[app_name]/restart.json
-## Storage nodes
-To store the distributable bees, you must start a storage backend. Beehive makes this easy again by using the start script:
+## Storage nodes
+
+To store the distributable bees, you must start a
+storage backend. Beehive makes this easy again by using the start
+script:
./scripts/start_beehive.sh -t storage
-Note, these storage backends must have git installed (currently the only supported scm) because they will clone the url repos (off-site for now) and squash the filesystem.
+Note, these storage backends must have git installed (currently the
+only supported scm) because they will clone the url repos (off-site
+for now) and squash the filesystem.
## Nodes
-Beehive is a distributed system. You can add multiple nodes in the router. The node_manager handles the node connections.
+
+Beehive is a distributed system. You can add multiple nodes in the
+router. The node_manager handles the node connections.
Viewing the nodes is as easy as a query as well:
curl -i beehive.com:8080/nodes
-To add a new node, as mentioned above, start a node with the seed value from the start script:
+To add a new node, as mentioned above, start a node with the seed
+value from the start script:
./start_beehive.sh -s 'router@my-other-machine.com'
@@ -112,24 +138,33 @@ To add an existing node to a cluster, you can set the seed with:
## Users
-Beehive has basic support for user accounts. The root user account information is:
+Beehive has basic support for user accounts. The root user account
+information is:
+
username: root@getbeehive.com
password: test
-It is strongly recommended that you delete this user as soon as you create your own (you must log in once with this user to create a new user).
+It is strongly recommended that you delete this user as soon as you
+create your own (you must log in once with this user to create a new
+user).
-Certain requests require an authenticated user. To remove the root@getbeehive.com user, we must authenticate. To authenticate, you must first get a token. This is achieved by submitting a request, such as:
+Certain requests require an authenticated user. To remove the
+root@getbeehive.com user, we must authenticate. To authenticate, you
+must first get a token. This is achieved by submitting a request, such
+as:
curl -i -XPOST -d"{\"email\":\"root@getbeehive.com\", \"password\": \"test\"}" http://beehive.com:8080/auth.json
This will return a tuple that will look like:
{"user":"root@getbeehive.com","token":"f24e53e38dfb380066ea166f1844cf19"}
-Subsequent requests that require authentication should attach this token onto the data.
+Subsequent requests that require authentication should attach this
+token onto the data.
-Of course, it would be wise to add another admin user first. To add an admin level user, use the level 1 and ass, such as below
+Of course, it would be wise to add another admin user first. To add an
+admin level user, use the level 1 and ass, such as below
curl -i -XPOST -d"{\"email\":\"arilerner@mac.com\", \"password\":\"myuniquepassword\", \"level\":\"1\", \"token\":\"f24e53e38dfb380066ea166f1844cf19\"}" beehive.com:8080/users/new.json
@@ -144,7 +179,11 @@ Advanced
## Custom event handlers
-The core functionality of Beehive is event-driven. It supports user defined callbacks as well. To hook into the beehive architecture, you will have to write a custom handler that exports the function: handle_event/1. And example of this custom event handler might look something like this:
+The core functionality of Beehive is event-driven. It supports user
+defined callbacks as well. To hook into the beehive architecture, you
+will have to write a custom handler that exports the function:
+handle_event/1. And example of this custom event handler might look
+something like this:
-module (my_callback_handler).
@@ -157,11 +196,16 @@ The core functionality of Beehive is event-driven. It supports user defined call
handle_event(_) -> ok.
-Notice that the module name is pretty unique. It's a good idea to stick to a unique name so as not to clash with Beehive modules.
+Notice that the module name is pretty unique. It's a good idea to
+stick to a unique name so as not to clash with Beehive modules.
-In any case, the handler for the event will catch the {bee, ready, Bee} event thrown when a backend has been released from a single connection.
+In any case, the handler for the event will catch the {bee, ready,
+Bee} event thrown when a backend has been released from a single
+connection.
-All the events in the source are thrown with the method: ?NOTIFY(EventTuple) and are documented throughout the source. Here is a brief list of the callbacks available to handle:
+All the events in the source are thrown with the method:
+?NOTIFY(EventTuple) and are documented throughout the source. Here is
+a brief list of the callbacks available to handle:
<table><tr><th>Event</th><th>Description</th></tr>
<tr><td>{bee, used, Bee}</td><td>When a connection has been established</td></tr>
@@ -182,9 +226,13 @@ To start a router with the custom callback module, use the -c and -a switches:
## Custom backend strategies
-Backends are chosen via a strategy. There are baked in strategies that can be used. Those are described in the file: [src/mesh/router/backend_strategies.erl](https://github.com/auser/beehive/blob/master/lib/erlang/src/mesh/router/bee_strategies.erl).
+Backends are chosen via a strategy. There are baked in strategies that
+can be used. Those are described in the file:
+[src/mesh/router/backend_strategies.erl](https://github.com/auser/beehive/blob/master/lib/erlang/src/mesh/router/bee_strategies.erl).
-If needed, custom strategies can be written to describe more complicated descriptions. To do so, write a custom handler, for instance:
+If needed, custom strategies can be written to describe more
+complicated descriptions. To do so, write a custom handler, for
+instance:
-module (custom_bee_picker).
-include ("/path/to/include/beehive.hrl").
@@ -193,11 +241,14 @@ If needed, custom strategies can be written to describe more complicated descrip
custom_chooser(Bees) ->
hd(Bees).
-This is clearly a dummy handler as it will choose the top of the bees, but it illustrates how to build a bee picker. To start with this bee picker at the top of the list:
+This is clearly a dummy handler as it will choose the top of the bees,
+but it illustrates how to build a bee picker. To start with this bee
+picker at the top of the list:
./scripts/start_beehive.sh -a /path/to/custom_callback_module -q channel_chooser
-Now, any application that has the routing_param set to channel_chooser will use the custom_chooser module.
+Now, any application that has the routing_param set to channel_chooser
+will use the custom_chooser module.
curl -i -XPOST -d"{\"token\":\"tokenofauthorizeduser\", \"name\":\"picky_app\", \"routing_param\":\"custom_chooser\", \"bee_picker\":\"custom_bee_picker\"}" beehive.com:8080/apps/new.json

0 comments on commit 9a514c7

Please sign in to comment.