Geosockets

Geosockets is a Node.js webserver and javascript browser client for rendering website visitors on a map in realtime using WebSockets and the browser's Geolocation API.

See the demo app at geosockets.herokuapp.com.

Using the Client Script on Your Site

The Geosockets javascript client can be used on any website:

<link rel="stylesheet" type="text/css" href="https://geosockets.herokuapp.com/styles.css">
<script src="https://geosockets.herokuapp.com/client.js"></script>
<script>window.geosocket = new Geosocket("wss://geosockets.herokuapp.com");</script>
<div id="geosockets"></div>

Use CSS to configure the size and position of the map container:

#geosockets {
  width: 100%;
  height: 100%;
}

The Server

server.coffee is a node app powered by express 3, node's native http module, and the einaros/ws WebSocket implementation. Express is used to serve the static frontend in /public.

When building web apps designed to scale, one should never assume that anything cached in memory or on disk will be available on a future request or job. Geosockets uses Redis to persist visitor data, treating Dynos as stateless processes: changes in the app's Dyno formation should be impercetible to users.

The Client

client.coffee is also written as a node app. Coffeeify, the red-headed step-child of browserify, is used in concert with Grunt to transpile the client into a single browser-ready javascript file.

When the client is first run in the browser, a UUID token is generated and stored in a cookie which is passed to the server in the headers of each WebSocket message. This gives the server a consistent way to identify each user.

The client uses the browser's geolocation API and the geolocation-stream node module to determine the user's physical location, continually listening for location updates in realtime. EOnce the WebSocket connection is establised, the client broadcasts its location to the server:

{
  uuid: '6e381608-2e63-4e40-bf6c-31754935a5c2',
  url: 'https://blog.heroku.com/archives/2013/10/3/websockets-public-beta',
  latitude: 37.7521248,
  longitude: -122.42365649999999
}

The client then listens for messages from the server, rendering and removing markers from the map as site visitors come and go.

Running Geosockets Locally

If you're new to Heroku or Node.js development, you'll need to install a few things first:

1. Heroku Toolbelt, which gives you git, foreman, and the heroku command-line interface.
2. Node.js
3. redis. If you're using homebrew, install with brew install redis

Clone the repo and install npm dependencies:

git clone https://github.com/heroku-examples/geosockets.git
cd geosockets
npm install

Fire up redis, a grunt watcher, and the node webserver at localhost:5000/?debug:

foreman start
```

## Debuggging

The client uses a custom logging function, found in `lib/logger.coffee`. This function
only logs messages to the console if a `debug` query param is present in the URL, e.g.
[localhost:5000/?debug](http://localhost:5000/?debug). This allows you to view client
behavior in production without exposing your site visitors to debugging data.

## Testing

Simple integration testing is done with [CasperJS](http://casperjs.org/), a navigation scripting & testing utility for [PhantomJS](http://phantomjs.org/). Casper is integrated into the app using the [grunt-casper](https://github.com/iamchrismiller/grunt-casper) plugin, and run with foreman. Each time you make a change to your client, the casper tests are run automatically.

### Deploying Geosockets to Heroku

```
heroku create my-geosockets-app
heroku labs:enable websockets
heroku addons:add openredis:micro # $10/month
git push heroku master
heroku open
```