Notice: This resource is no longer being actively maintained and as a result some information may be out of date or inaccurate. Please see for technical instructions or for support related concerns.
RUN@cloud » WebSocket


Last modified by Michael Neale on 2013/04/12 04:55

WebSocket allows your app to have a "full duplex" connection - either via upgrading from an HTTP 1.1 connection or by directly connecting from a client (mobile, or modern web browser). Your application can then pass messages from server to client and vice versa. Service side "pushing" of messages is often done this way (although there are many ways) for interactive apps that need updates as the data changes. Read on for some examples of this (or if you don't already know you want to use them!). 

NOTE: WebSocket is now generally available

WebSocket is provided via a nginx - which has recently been rolled out on the CloudBees platform.  Also note: if you have an existing "older" SSL revproxy (created early 2013) - you will need to open a ticket if you want it to be upgraded (easily done, but you need to ask). For new SSL revproxies, and apps using shared service (eg free apps, non SSL) - they can continue as below.

Configuring your app to use WebSocket

Stupidly simple, you need a parameter set for your application that tells it to use http 1.1 (this allows upgrading to websocket, if asked for): 

For example:

bees app:proxy:update -a APPID http_version=1.1

You can als pass the http_version parameter when deploying an app - in any case, you only have to set it once, from then on it will be websocket ready. 

We will possibly make this a default in future releases. Note that this prepares the cloudbees *platform* for websocket - it is up to each container as to how it implements websocket. 

You can also use SSL - if you have a SSL revproxy. As mentioned above, if you have an older/existing SSL revproxy service - you will want to open a ticket to ask us to upgrade it (but any new ones will be fine).

Want to try it in a ClickStart: 


How it works

The revproxy layer - which is built around NGINX, now has a version of NGINX that is able to proxy HTTP 1., and accept WebSocket connections. Further to this, HTTP 1.1 "upgrade" requests are honoured (whereby a connection can switch into WebSocket, while starting out as HTTP 1.1). 


On the left, we have a "classic" HTTP app with non-WebSocket proxying, using HTTP 1.1 to the revproxy (HTTP 1.0 also works). This setup allows for efficient Internet scale connections. The connection from the revproxy to the upstream application servers (basically everything behind the revproxy) can be either HTTP 1.1 or 1.0 - however, the connection here is not related to the HTTP 1.1 connection to the client devices. The choice of protocol between the web server and the app server is a configuration choice made by the CloudBees PaaS. 

On the right, HTTP 1.1 is used both from the client to the revproxy, and from the revproxy to the upstream application. However, in this case, the revproxy knows how to upgrade the connection to WebSocket - if it is asked to (from which point, the connection resembles a direct lower-level connection to the upstream application server). The revproxy also knows how to route ws:// style requests directly (no upgrade from HTTP 1.1 needed). It is important to know that all requests still go through the revproxy layer - and when a connection is established, the revproxy will balance the request according to load balancing rules. Once the WebSocket "connection" is established, messages can flow freely in both directions as if the revproxy wasn't there.

Example apps

If you'd like a better understanding of the power of WebSocket, or to play around with some working examples, here are a couple that you should enjoy.

WebRTC - video chat

WebRTC is a javascript library that exposes the "real time communications" (video and voice) features of Chrome and Firefox (at the moment) - allowing a very simple video chat app to be built (see source here):


The app is currently running here - if you have the latest Chrome (or a nightly Firefox build) you can try it. 

This application uses the latest production Chrome browser - but it also works with Firefox nightly builds at the time of writing. The ClickStart is based on this project.


If you run this you will need to apply the domain name change described previously, for it to work. 

Text chat

The Play! framework comes with a sample WebSocket-only app for real time chat. This app is currently running here.


This example uses full duplex connections to push messages back and forth.

How to build WebSocket apps

The best way to get started is to look for examples in your framework of choice - Play2 and are both notable framework examples. There are many javascript clients that can do WebSocket in a way that lets your connection degrade to http/long polling (remember that in some cases there may be other things between your client and the revproxy to disrupt the connection).

If you find other interesting apps, please let us know!


Ask on the dev mailing list - or open a ticket. You can also find us on #cloudbees on

Created by Michael Neale on 2013/02/04 23:40