by OmarElGabry



Dependency Status Scrutinizer Code Quality Code Climate

A Real Time Chat Application built using Node.js, Express, Mongoose,, Passport, & Redis.



Check Demo



Running Locally

Make sure you have Node.js and npm installed.

  1. Clone or Download the repository

    $ git clone
    $ cd
  2. Install Dependencies

    $ npm install
  3. Edit configuration file in app/config/config.json with your credentials(see Setup Configurations).

  4. Download and Install Redis.

  5. Running Redis Server(as Admin)

    $ redis-server
  6. Start the application

    $ npm start

Your app should now be running on localhost:3000.

Deploying to Heroku

Make sure you have the Heroku Toolbelt installed.

  1. Create a new Heroku application, and push your chat application to a Git remote repository

    $ heroku create
    $ git push heroku master


    Deploy to Heroku

  2. Now, you need to set up configuration variables on Heroku.

    1. Go to Settings -> Reveal Config Vars.
    2. Add configuration variables. All needed variables are inside app/config/index.js. Typically, these are the configuration variables you need to assign: { dbURI, sessionSecret, facebookClientID, facebookClientSecret, twitterConsumerKey, twitterConsumerSecret }(see Setup Configurations).
  3. One last step is to add Redis as an Add-on on Heroku.

    1. Go to Resources -> Add-ons
    2. Select Heroku Redis

    You need to setup a billing account even if the add-on is free.

  4. Open your chat application in the browser

    $ heroku open

How It Works

Setup Configurations

The configurations on production will be assigned from Environment Variables on Heroku, while the development configurations reside inside app/config/config.json file.

MongoDB & MongoLab

You need to create a database on MongoLab, then create a database user, get the MongoDB URI, and assign it to dbURI.

Facebook & Twitter

You need to register a new application on both Facebook and Twitter to get your tokens by which users can grant access to your application, and login using their social accounts.

Registering the app on Facebook
  1. Go to Facebook Developers
  2. Add new app, and fill the required information.
  3. Get your App ID, App Secret.
  4. Go to Add Product -> Facebook Login -> Valid OAuth redirect URIs
  5. Add Valid Callback URIs
  6. Go to App Review -> Make your application public.

Now, you can assign the App ID to facebookClientID, and App Secret to facebookClientSecret.

Registering the app on Twitter
  1. Go to Twitter Apps
  2. Create new app, and fill the required information.
  3. Add Website & Callback URL
  4. Get your Consumer Key, Consumer Secret.

Now, you can assign the Consumer Key to twitterConsumerKey, and Consumer Secret to twitterConsumerSecret.

The Callback URL


The session needs a random string to make sure the session id in the browser is random. That random string is used to encrypt the session id in the browser, Why? To prevent session id guessing.


Mongoose is used to interact with a MongoDB that's hosted by MongoLab.


There are two schemas; users and rooms.

Each user has a username, passowrd, social Id, and picture. If the user is logged via username and password, then social Id has to be null, and the if logged in via a social account, then the password will be null.

Each room has a title, and array of connections. Each item in the connections array represents a user connected through a unique socket; object composed of {userId + socketId}. Both of them together are unique.


Each model wraps Mongoose Model object, overrides and provides some methods. There are two models; User and Room.


Session in Express applications are best managed using express-session package. Session data are stored locally on your computer, while it's stored in the database on the production environment. Session data will be deleted upon logging out.

User Authentication

User can login using either a username and password, or login via a social account. User authentication is done using Passport. Passport has extensive, and step-by-step documentation on how to implement each way of authentication.


Having an active connection opened between the client and the server so client can send and receive data. This allows real-time communication using TCP sockets. This is made possible by

The client starts by connecting to the server through a socket(maybe also assigned to a specific namespace). Once connections is successful, client and server can emit and listen to events.

There are two namespaces used; /rooms and /chatroom.


And It doesn't go without saying, you need to monitor your application. Winston can log and catch Uncaught Exceptions. All logs are displayed in the console, and saved in debug.log file.

On Heroku, you can monitor the logs by clicking on More -> View Logs on the top left of your application dashboard.


I've written this script in my free time during my studies. If you find it useful, please support the project by spreading the word.


Contribute by creating new issues, sending pull requests on Github or you can send an email at:


Built under MIT license.