From bc34e5891d959111569cfe115c0fdc0ce43d90dc Mon Sep 17 00:00:00 2001 From: Chris Tavares Date: Mon, 18 Mar 2013 14:04:10 -0700 Subject: [PATCH] Added readme for chat sample --- examples/chat/readme.md | 103 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 examples/chat/readme.md diff --git a/examples/chat/readme.md b/examples/chat/readme.md new file mode 100644 index 0000000..2580ce8 --- /dev/null +++ b/examples/chat/readme.md @@ -0,0 +1,103 @@ +# socket.io chat, with Azure Service Bus + +This example is a slightly-tweaked version of the canonical socket.io chat application. +It has been updated to use Express version 3 and the socket.io-servicebus library +as a back-end store to allow chat to work across multiple servers. + +# Running the app + +## Set up Service Bus + +To run an instance of the chat app, you have to set up a service bus namespace and topic +first. + +1. Create (or locate) a Service Bus namespace to use. Get the connection string for this namespace + either from the Windows Azure portal or by using the azure command line tools. + +2. Create a topic in the Service Bus namespace. Default settings for the topic will work fine. + +3. Create subscriptions in the Service Bus topic; each instance of the chat app will need it's own, + distinct subscription. Default settings for the topic will work fine. + +## Running the application + +Before you run, you'll need to run `npm install` in the chat example's directory to set up dependencies. + +### Command line parameters + +Once you have Service Bus set up, run the application. The command line looks like: + +``` + node app.js +``` + +`` is the topic name, `` is the subscription name for this instance, +`` is the port number to run on, and `` is the service bus connection string. + +### Environment variables + +The app will read missing command line values from environment variables (particularly useful if deploying +to Windows Azure): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable NameUsage
SB_CONNService bus connection string
PORTPort number
SB_CHAT_TOPICTopic name
SB_CHAT_SUBSCRIPTIONSubscription name
TEST_SB_CHATFor local tests; uses socket.io-servicebus module from source tree rather than npm
+ +The `TEST_SB_CHAT` environment variable is not represented on the command line. If you're making changes to the socket.io-servicebus +module itself, turning this environment variable on (set it to any value, it just has to exist) will cause the chat app to +require the module from the source tree directly, rather than using the one npm installed locally. + +# Known Issues + +* The setup for service bus should not require setting up subscriptions manually; this is planned for a future version. + +* The "presence" messages (list of who has joined the chat) is not currently working correctly across multiple nodes. This + is a known issue with the chat app itself; you see similar issues when using the redis store. + +# Places to look + +The most important part of this code is in app.js file. Look for the call to io.configure. This call is where we set up Service Bus as the +store. + +# Need Help? + +Be sure to check out the Windows Azure [Developer Forums on Stack Overflow](http://go.microsoft.com/fwlink/?LinkId=234489) if you have trouble with the provided code. + +# Contribute Code or Provide Feedback + +If you would like to become an active contributor to this project please follow the instructions provided in [Windows Azure Projects Contribution Guidelines](http://windowsazure.github.com/guidelines.html). + +If you encounter any bugs with the library please file an issue in the [Issues](https://github.com/WindowsAzure/socket.io-servicebus/issues) section of the project. + +# Learn More + +For documentation on how to host Node.js applications on Windows Azure, please see the [Windows Azure Node.js Developer Center](http://www.windowsazure.com/en-us/develop/nodejs/). + +For documentation on the Azure cross platform CLI tool for Mac and Linux, please see our readme [here] (http://github.com/windowsazure/azure-sdk-tools-xplat)