Documentation

Simply put, Orbited allows you to communicate in real-time with your visitors. Using streaming networking for JavaScript we have:

  1. Real-time communication between your server and your visitors
  2. No loading bar, page refreshes or click sounds (IE)
  3. The ability to simultaneously push data to all, or some, of your visitors

Orbited allows you to write real-time web applications, such as:

  1. Chat rooms
  2. Instant messaging clients
  3. Live graphs and information tickers
  4. Make use of live events (real-time updating a page)

All without Flash or java. To accomplish these objectives Orbited bridges TCP streams to your browser. Thus, you can connect your clients to any TCP/IP service (IRC servers, custom applications, STOMP daemons such as RabbitMQ and ActiveMQ). Orbited uses js.io to hande protocols such as IRC and STOMP.

Orbited is installed on a subdomain and all communication is over port 80 so normal firewalls will not block it. Orbited are currently tested to work in:


Table of contents


  1. Documentation ¶
    1. Table of contents
    2. Network setup - An overview
      1. Network setup - STOMP
      2. Network setup - subdomains and network architecture
    3. Obtaining and Installing
      1. Obtaining
      2. Pre-requisites - dependencies
      3. Compiling
      4. Installing on Windows
    4. Configuration
      1. Configuration directives
      2. [global] Section ¶
        1. reactor ¶
        2. proxy ¶
      3. [listen] Section ¶
      4. [static] Section ¶
      5. [ssl] Section ¶
      6. [access] Section ¶
      7. [logging] Section ¶
      8. [loggers] Section ¶
    5. Setting up your first example
    6. Deploying Orbited - Running as daemon
    7. Orbited Performance
      1. Benchmarks
        1. The test
        2. The sponsor
        3. The result
      2. How to benchmark
    8. Scaling Orbited
  2. Development
    1. Using TCP Socket
    2. Connecting Orbited to Flash
    3. Running Orbited, Webserver and HA-Proxy on the same Server
    4. Advanced: TCP Socket
    5. Handling static files

Network setup - An overview

[ Network setup, overview, include cloud-wireframe here to demonstrate visually ]


Network setup - STOMP

[ Be sure to mention it has a built in STOMP server ]
[ Include info from thread ]
[ Include info from http://orbited.org/wiki/MorbidQ ]

Network setup - subdomains and network architecture


We need info here..

Obtaining and Installing

Obtaining

Download..

Pre-requisites - dependencies

Orbited uses Twisted as its event driven network engine. It's the core of the network communications in Python.


Compiling

After installing dependencies, do this.

Installing on Windows

To install on Windows, do this.

Configuration

On Unix systems Orbited looks for a configuration file in /etc/orbited.cfg when started. On windows it looks for "\Program Files\Orbited\etc\orbited.cfg" when started. If neither of these file are found, it will look for orbited.cfg in the directory it is run from. You can also manually specify the location of the configuration file with the --config option. If no configuration file is found, Orbited refuses to start.

Configuration directives


Orbited ships with the following example configuration:


# Example Orbited Configuration file

[global]
reactor=select
# reactor=kqueue
# reactor=epoll
proxy.enabled = 1
session.ping_interval = 40
session.ping_timeout = 30

[listen]
http://:8000
# uncomment to enable ssl on port 8043 using given .key and .crt files
#https://:8043
#
#[ssl]
#key=orbited.key
#crt=orbited.crt

[static]

[access]
localhost:8000 -> irc.freenode.net:6667
* -> localhost:4747
[logging]
debug=STDERR,debug.log
info=STDERR,info.log
access=STDERR,info.log
warn=STDERR,error.log
error=STDERR,error.log

#Don't enable debug by default
enabled.default=info,access,warn,error

# Turn debug on for the "Proxy" logger
[loggers]
#Proxy=debug,info,access,warn,error

[global] Section

reactor


The reactor is the network core of the event loop within Twisted -- the loop which drives applications using Twisted. The reactor provides basic interfaces to a number of services, including network communications, threading, and event dispatching. Different reactors are best suited for different OS. For more information about the basics of a reactor, visit Twisted Reactor Overview.


Orbited uses the "select" reactor by default; this is because it's available for all platforms (and only option on Windows). But while it's a good reactor while developing your application, it has scalability issues. On Linux you should choose "epoll" and on OS X/FreeBSD you should choose "kqueue". For more information about reactors consult the Twisted Choosing a Reactor How To.

proxy

The proxy directive enables orbited to relay connections between the user and a third-party server (over TCP/IP). More technially, it enables the use of the proxy through the Orbited.TCPSocket JavaScript object. The proxy is enabled by default and there is no reason to turn this off.

[listen] Section

In general, the listen section describes the interfaces and ports Orbited should bind and listen to. Each line specifies a protocol, interface, and port in the form of a URI. The interface and port tell Orbited _where_ to listen, and the protocol tells it _what_ kind of traffic to expect. There are two basic types of protocols: those that allow a browser to establish a Comet Session, and those that function as standalone servers.


The first category is what Orbited is all about: listening for http and https. Lines beginning with http or https instruct Orbited to listen for http or https connections and proxy those connections in one way or another. This is what enables browsers to connect to the daemon, and Orbited will not work without an http or https line.


A line beginning with some other protocol instructs the daemon to start a certain type of server. This second category is composed of the following options: echo, lineecho, rude, announce, monitor, and stomp. The first four are simple servers that the developer can use to test a deployment or diagnose network problems. A line beginning with stomp:// instructs the Orbited daemon to start the integrated STOMP server, MorbidQ (described in Network setup - STOMP). A line beginning with monitor:// tells Orbited to serve system resource information (available at http://[orbited_interface]:[orbited_port]/system/monitor). Remember: a listen section entry of this type (non-http, non-https) only tells Orbited to listen for a certain type of traffic on a certain port and interface --  a corresponding line in the access section is required for end-users to actually connect.


[listen]
http://:8000 # listen for HTTP on port 8000
https://localhost:443 # listen for https on port 443 on the localhost interface
http://10.0.0.1:80 # listen for HTTP on port 80 on the interface 10.0.0.1
stomp://:61316 # enable MorbidQ and have it listen on port 61613
echo://:8001 # run an echo server on port 8001
monitor://:8005 # provide system information feed on port 8005

[static] Section

The static section allows rudimentary configuration for static content. You can configure an arbitrarily named virtual directory under root (You can't use 'static', 'proxy', 'binaryproxy', or 'websocket') to point at an arbitrary on-disk location. You can also set a particular file or directory to serve the as the root content by specifying the named virtual directory INDEX. Here are some examples:


INDEX=/home/mcarter/website/index.html # will serve the specified "index.html" file as "/"
javascript=/home/mcarter/dev/coolprojects/js # serves .../coolprojects/js/* as /javascript/*

More about static files in the "handling static files" section.

[ssl] Section

In order for listen URIs of the form https:// to work, the ssl section much be present (and python-openssl needs to be installed). This section needs to point to the key and certificate files used for ssl encryption. An example of this configuration is:


[ssl]
key=/etc/orbited/ssl.key
crt=/etc/orbited/ssl.crt

[access] Section

The access section is where authorization for routing is defined. It is a white list that specifies every remote hostname and port that a browser is allowed to connect to through orbited. If a host:port pair doesn't appear in this list, Orbited will not proxy data to that destination. Simply put: this is were you define which servers and ports your users will be able to connect to. An entry is necessary for _every_ server your user must access, including non-http, non-https entries in the listen section. Some examples in this section are:


[access]
* -> localhost:9998 # Allow connections from the browser to be proxied locally to port 9998. Note that the hostname *must* be "localhost" and not an equivalent like "127.0.0.1"
* -> activemq.domain.com:61613 # Allow STOMP connections to "activemq.domain.com" on port 61613. Note that connections to "domain.com" or "node1.activemq.domain.com" will be rejected.

Note that the above examples both use the left-hand side (LHS) rule of "*". The LHS of each access rule refers to the HTTP Host header value that is allowed. For instance, If I were to visit http://orbited.org:8000/static/demos/chat, then my browser would send the host header "orbited.org:8000". Therefore, I need to have an LHS value of "orbited.org:8000". Of course, the wildcard "*" would work as well. The reason for this rule is to allow you to protect against variants of the Princeton attack. It's a good idea to use '*' when developing, but once you know the hostname and port that you are going to use for deployment, put those in as the LHS. Some examples:


[access]
localhost -> irc.freenode.net # allow access with hostname localhost (implied port 80) to make proxy requests to irc.freenode.net
orbited.org:8000 -> localhost:61613 # allow access with hostname orbited.org:8000 to make proxy requests to localhost:61613 (local activemq server)

[logging] Section

The logging section allows you to specify where output to various types of messages go. The message types are:


The output can be sent to multiple files or the screen. Here are some example configurations:


[logging]
debug=SCREEN # send debug output to the screen
info=SCREEN,/var/log/orbited/info.log # send info output to the screen and the file "/var/log/orbited/info.log"
access=/var/log/orbited/access.log # send access output to the file "/var/log/orbited/access.log"
warn=/var/log/orbited/error.log # send warn output to the file "/var/log/orbited/warn.log"

# send error output to the SCREEN, the file "/var/log/orbited/error.log" and the file "home/mcarter/sever/orbited_error.log"
error=SCREEN,/var/log/orbited/error.log,/home/mcarter/sever/orbited_error.log

NB: Besides SCREEN (aka STDOUT), you can also redirect the output to STDERR. (only available after [357]).

[loggers] Section

this section is used to provide custom logging configuration for individually named logging components in Orbited. For now, this feature is primarily used to provide extensive debugging output to developers. Some of the logging component names include:



While this configuration section can be used to enable output for a particular logging component, the [logging] section still determines where that output goes, whether its the SCREEN or an arbitrary file, or nowhere. An example of enabling debug output for the Proxy code looks like this:


[loggers]
Proxy=debug,info,access,warn,error # turn all output on for the Proxy component



Setting up your first example


Deploying Orbited - Running as daemon

http://orbited.org/wiki/Deployment

Scaling Orbited

- Share nothing
- Horisontal scaling
- Add howto
- Add real world example

Development

http://orbited.org/wiki/Development

Using TCP Socket

http://cometdaily.com/2008/07/01/sockets-in-the-browser/

Connecting Orbited to Flash

Take information from Google Group

Running Orbited, Webserver and HA-Proxy on the same Server

More information about Running Orbited, Webserver and HA-Proxy on the same server can be found at Google grop

Advanced: TCP Socket

More information about TCP Socket can be found at http://orbited.org/wiki/TCPSocket


Handling static files


Orbited has built-in support for handling static files (these includes the core JS, cross-communication bridge and demos). However, while convenient it is not mandatory to serve these files from Orbited. However, if you choose to server the html bridge file yourself, remember that you then need to set "Orbited.settings.hostname" and "Orbited.settings.port" yourself. This would allow you to serve your static files on a light webbserver (such as nginx or lighttpd).