WebSocket on Simple Hosting

WebSocket support is now available in Alpha testing for Simple Hosting Node.js in the FR-SD2 datacenter (Paris, France).

This document provides a general overview and a detailed example of how to enable WebSocket support for your Node.js instance.

We encourage you to try it out and to give us your feedback.

How it works

Let's say that you're running a website on a Simple Hosting instance with example.com and www.example.com as Websites / VHOSTS.

Simple Hosting listens to HTTP(s) requests made to example.com and www.example.com on ports 80 and 443 with the Web Accelerator, our load balancing service. It receives, decrypts and forwards those requests to your instance internally on a pre-set port, for example 8080.

We are currently Alpha-testing a new secure TCP load balancing service that adds support for other protocols, including WebSocket. It listens exclusively on port 443 and requires an SSL certificate to work. For now, the service is only available on the FR-SD2 datacenter (Paris, France) for Node.js instances.

Because it does not listen on port 80, it is not meant to replace your current Website / VHOST configurations. All HTTP(S) requests should remain directed to 'www.example.com' and 'example.com'. Only WebSocket requests should point to the new load balancing service.

To enable WebSocket support for your instance, all you need to do is create a new DNS record for live.example.com and add an SSL certificate along with a VHOST. Your code can then point WebSocket requests to:

wss://live.example.com

Your instance will receive WebSocket requests on the normal HTTP port, and they will already be decrypted. You don't need to listen on any extra ports nor configure SSL support in your application.

Requirements

You'll have to meet the following requirements to use the WebSocket protocol on your instance:

  • A Simple Hosting instance of size M or above, to support SSL
  • Your instance must be running in the FR-SD2 datacenter (Paris, France) during the Alpha testing phase
  • A new subdomain for WebSocket requests and its corresponding VHOST
  • An SSL certificate for that VHOST

Setup instructions

It's important to remember that you should use a dedicated subdomain to handle WebSocket communication with our service. Make sure you read the “How it works” section before you continue.

Add a Website / VHOST to your instance

Now, create a Website / VHOST listing for your instance. It will let the load balancing service know where to send the requests addressed to live.example.com.

With Gandi CLI, all you have to do is run the following command:

  $ gandi vhost create live.example.com --paas {myinstance} --ssl

On the instance's Admin interface, you can click on the “Add” button located below in the “Websites” section.

You can find your instance in the listing: https://www.gandi.net/admin/hosting/paas/management

In the Admin interface, make sure you do not opt for automatic DNS management when adding the VHOST. The next section will walk you through the required manual DNS settings.

Create a DNS record for your subdomain

The first step is to create the subdomain dedicated to your WebSocket communications.

All you have to do is add an A-type DNS record pointing to the load balancer's IP address.

If your domain is managed with Gandi, you can run the following command with Gandi CLI:

  $ gandi record create --name live.example.com --type A --value 217.70.180.161 --ttl 3600

You can also create the record on the Admin interface: https://www.gandi.net/admin/domain/zone/list

Example zone file:

  $ORIGIN example.com.
  $TTL 1h
  ...
  live  IN  A   217.70.180.161

Add the SSL certificate

If you already own a certificate, you can add it to the Certificate Store with Gandi CLI:

  $ gandi certstore create --crt /path/to/cert --pk /path/to/key

On your instance's Admin interface,click on the padlock icon to the right-side of your Website / VHOST to upload your certificate.

To create a certificate, you can run the following command and follow the steps in Gandi CLI:

  $ gandi certificate create

You can also easily create a certificate through our website: https://www.gandi.net/ssl

Remember that Gandi Domain customers get a free standard certificate for one year with every domain bought or transfered to Gandi.

Once you have created your certificate, make sure you add it to the Certificate Store as previously described.

Setup your application code

In your code, you can point your WebSocket requests to your new secure VHOST on port 443:

  wss://live.example.com:443

Port 443 is the default port for secure WebSocket, so you can probably leave it out with most clients.

Go ahead and test your WebSocket-powered application. For example with curl:

  $ curl -i -N \ 
    -H "Connection: Upgrade" \
    -H "Upgrade: websocket" \
    wss://live.example.com

Or with JavaScript:

  var conn = new WebSocket('wss://live.example.com');
  
  conn.onopen = function(e) {
    console.log("Connection established!");
    conn.send('Hello World!');
  };
  
  conn.onmessage = function(e) {
    console.log(e.data);
  };

Remember that your instance's port remains the same and that your instance won't receive encrypted communication.

The SSL encryption terminates on the load balancing server, which then forwards the requests internally on Simple Hosting's private network as it normally does.

You don't need to configure your application to handle SSL communication nor listen on any other port.

You won't notice any extra CPU load either, since the service does all the heavy lifting :)

Last modified: 04/06/2016 at 13:01 by Alexandre L. (Gandi)