Platform Customization

If you’re an Ably Enterprise customer, then you can optionally create a custom environment to tailor the Ably platform to your specific requirements. A custom environment enables you to benefit from the following:

• Active traffic management: Let Ably actively monitor not only the global cluster health but also your own endpoints and proactively take steps to isolate or move traffic to ensure business continuity.
• Dedicated, isolated clusters: Rely upon guaranteed capacity and isolation from noisy neighbors.
• Regional routing of traffic: Require that all traffic is routed and serviced within specific regions.
• Regional message storage: Require that all messages are stored within a specific region.

A custom environment provides you with your own endpoints to service Ably platform requests. These can be either subdomains of ably.io, or point at your own custom CNAME domain. If you choose the latter option, Ably can also customize our client library SDKs to use your chosen domain and make them available via our CDN as cdn.ably.com/lib/yourcompany.min.js.

If you are not currently an enterprise customer but are interested in finding out more, then please get in touch.

If you’re ready to enable a custom environment to take advantage of these features, then please see our guide. Otherwise, read on to find out more.

Active traffic management (ATM) is a feature available exclusively to our Enterprise customers that enables the Ably engineering team to manage the endpoints that customers connect to.

This ensures that under adverse conditions, such as a denial of service attack or a major outage, Ably can proactively route Enterprise customer traffic to specific data centers or regions that are unaffected, or even to new temporary clusters. This enables customers to maintain service while the issue is investigated and resolved.

This service is ideal for customers who want reassurance that Ably actively monitors not only the global cluster health but also the endpoints used by that customer, and can act to isolate or move traffic, ensuring business continuity.

As part of our Enterprise package offering, Ably are able to offer customers dedicated clusters that are either partially or completely isolated from our global cluster. Customers who require isolation from our global cluster for security, governance or guaranteed capacity reasons are able to run the Ably platform on their own EC2 dedicated environments.

This involves the provision of dedicated realtime and routing servers, with shared database cluster and common services (such as stats, logging, registries, and configuration).

We provide you with custom endpoints for your cluster, for example: yourcompany-realtime.ably.io and yourcompany-realtime.ably.io. Additionally, we can support CNAMEs using your own custom root domain.

Please note the following:

• Ably only supports Amazon EC2 environments (within Virtual Private Networks)
• Ably is responsible for pro-actively managing and updating dedicated clusters
• Dedicated clusters can run in one or more regions of your choice

If you would like to find out more about our dedicated cluster offering, please get in touch.

If you need your data to remain within either Europe or the US, we can customize your account so that all of your data (both stored data and transient realtime data transmission activity) is kept in servers within the EU or US.

Note that this does not prevent customers outside of your chosen region from connecting to Ably – it just means that, regardless of their location, they will connect to a datacenter in that region.

If you are interested in applying processing or storage constraints to regions other than Europe or the US, then please speak to your customer success manager.

To implement regional restrictions at the application level, you must specify the required environment after configuring your account for regional routing and storage. Specify the required environment: eu or environment: us in the Ably client options ( Rest SDK and Realtime SDK ) when you are initiating the connection, from both the publisher’s and subscriber’s side.

Note: This approach does not apply regional restrictions when you are using a persistent history feature. For implementing geolocation restrictions on history, you would need to set a placement constraint to ensure data stays in the EU or any designated region.

To use a custom environment, perform the following steps:

Ably client libraries connect to two endpoints by default:

• realtime.ably.io – this endpoint is used for all WebSocket and other realtime protocol connections from the Ably client libraries.
• rest.ably.io – this endpoint is used for all REST-based requests and is optimized for all standard HTTP-based request types including all REST requests, authentication requests, and Comet and JSONP fallback when WebSockets cannot be used.

When you request a custom environment, you have the following options:

For example, example-rest.ably.io and example-realtime.ably.io.

These use Ably’s existing wildcard certificate, which supports *.ably.io and *.ably-realtime.com.

For example, rest.ably.example.com and realtime.ably.example.com.

Ably issue the certificate, based on you configuring a CNAME DNS record or adding another record on *.ably.example.com that authorizes issuing a certificate for that subdomain. That means that the setup only needs to be done once, and doesn’t require any additional manual intervention each time the certificate needs renewal.

This approach is also much less risky than handing out the wildcard *.example.com certificate.

As an example, here is how this would work:

• realtime.ably.example.com is used for the primary endpoint
• [a-e]-fallback.ably.example.com is used for the fallback domains
• Ably issue a certificate for ably.example.com and *.ably.example.com, which is a CNAME DNS record set up by the customer for that subdomain.

Note: By default, Ably serves fallback traffic under the *.ably-realtime.com domain which is managed separately to the main *.ably.io domain. This means even problems at the DNS or registrar level on the primary ably.io domain can be routed around using the fallback mechanism.

In addition, Ably handle all certificate renewals, rolling out to our global endpoints, load balancers, and so on, without ever having to coordinate with you manually to get new certificates issued. This makes life easier for both you and Ably.

When using your own custom domain, Ably provide these DNS records for you to CNAME to. Although it is recommended that you implement a similar architecture by using CNAMEs under two different domains (for example, ably.example.com for your primary traffic and ably.fallback-example.com for your fallback traffic, with the latter hosted with a different registrar and using different name servers to the first), this is not mandatory. Therefore, the decision as to whether you need that extra level of redundancy within your own DNS system is yours.

To enable a custom environment for your enterprise, speak to your customer success manager. They will create the custom environment for you and provide you with a ClientOptions object, containing the following properties:

• environment: the name of your custom environment. Provide this option when the hostname for realtime (Websocket) and REST (HTTP) connections is the same. Otherwise, specify the following options instead of environment:
  • realtimeHost: the hostname to use for realtime (WebSocket) connections.
  • restHost: the hostname to use for REST (HTTP) connections.
• fallbackHostsUseDefault: whether to use the standard fallback hosts when an error requires the use of an alternative host. If you have a single host for both realtime and REST connections and specify that hostname using the environment flag, then setting this option to true will automatically determine which fallback hosts to use.
• fallbackHosts : an array of custom fallback hosts to try if an error requires the use of an alternative host. Ensure that you set these manually if specifying realtimeHost and restHost instead of environment.

Test your custom environment by visiting your new endpoints. The URL for your endpoints will depend on whether you have opted to use an Ably subdomain or a custom CNAME domain.

For example, if you have elected to use an Ably subdomain, you should test your environment by replacing [ENVIRONMENT] with the value of the environment property in the ClientOptions object:

• Realtime: https://[ENVIRONMENT]-realtime.ably.io/time (e.g. https://environment-example-realtime.ably.io/time)
• REST: https://[ENVIRONMENT]-rest.ably.io/time (e.g. https://environment-example-rest.ably.io/time)

Repeat this step for all fallback hosts in the fallbackHosts array, if provided.

Now that you have tested your custom endpoints, you must modify your code to instantiate the Ably client with the provided ClientOptions.

The following example demonstrates how to set up the Ably Realtime client using an Ably subdomain:

JavaScript
Select...

const ably = new Ably.Realtime({
  authUrl: '/auth', // Your authentication URL
  environment: 'example-environment', // Replace with your custom environment name
});

Copy
Copied!

The following example demonstrates how to set up the Ably Realtime client using your own subdomain:

JavaScript
Select...

const ably = new Ably.Realtime({
  authUrl: '/auth', // Your authentication URL
  realtimeHost: 'realtime.example.com', // Your custom WebSocket endpoint
restHost: 'rest.example.com', // Your custom REST endpoint
  fallbackHosts: [
    'a-fallback.ably.example.com',
    'b-fallback.ably.example.com'
  ]
});

Copy
Copied!

You should then test that all client SDKs can connect, publish, and receive messages (where applicable) before rolling out these changes to production code.

Where possible, you should also inspect your network traffic to verify that the client SDKs are calling the endpoints for your custom environment. Instead of connections to realtime.ably.io you should see connections to [ENVIRONMENT]-realtime.ably.io, or your own custom CNAME domain.

Once all your client library SDKs are using the new environment and traffic is arriving at the correct endpoints, the team at Ably will be able to actively reroute your traffic based on your environment settings.

If you have regional constraints on your account, then please contact your customer success manager who will ensure that the regional constraints are applied and tested too.

Note: Services are assigned to a custom environment on a per-account basis. This means that all apps within an account must be migrated at the same time.