Ably's Committed Use customers optionally have access to custom environments, dedicated clusters and the capability to restrict all traffic, data and storage to specific regions. Customers using custom environments can benefit from our Active Traffic management service.
Note: We also support custom CNAME domains such as yourcompany.com. Get in touch if you would like to set this up as the setup instructions differ from custom environments.
If you have been assigned a custom environment and/or set of custom fallback hosts, you must follow the steps below when configuring your client library SDKs.
Please note that services are assigned to a custom environment on an account basis. This means that all apps within an account must be migrated at the same time; the configuration changes described below must be applied for all apps belonging to the account in question.
1. Get your environment set up with the help of Ably
Please speak with your customer success manager about configuring your custom environment. A custom environments will have one or more of the following provided by the Ably platform
- Active traffic management
- Dedicated clusters
- To Isolated from noisy neighbours and guaranteed capacity
- Regional routing of traffic and message storage
- Limiting all traffic to be routed and serviced only within the EU or US for example
- Limiting all messages stored to be only within the EU or US for example
Your customer success manager will provide you with one or more of the following ClientOptions (constructor options) that must be used in all your Ably client library SDKs:
- environment
- fallbackHostsUseDefault (optional)
- fallbackHosts (optional)
Once you have been provided with a custom environment, you can test this is working by visiting the following URLs (replace [ENVIRONMENT] with your supplied environment):
- https://[ENVIRONMENT]-rest.ably.io/time
- e.g. https://environment-example-rest.ably.io/time
- https://[ENVIRONMENT]-realtime.ably.io/time
- e.g. https://environment-example-realtime.ably.io/time
You can do the same with any fallback hosts you are provided.
You are now ready to set up your clients. However, please bear in mind:
- If you have regional constraints for your account (see links above), Ably will not yet have this enabled. This is to ensure that any traffic arriving in an incorrect region due to clients not being configured correctly is not yet rejected. Once you confirm all clients are configured with the correct environment and fallbacks, the regional constraints will be added and enforced.
2. Modify your client library SDKs to use the correct environment settings
The ClientOptions provided to you by your customer success manager must be used in all of your client library SDKs. Here is an example of a Javascript client initialized with a custom environment and set of fallback hosts:
var ably = new Ably.Realtime({ authUrl: '/get-token',
/* your token callback code, authUrl, or key */ environment: 'environment-example', fallbackHosts: [ 'environment-example-a-fallback.ably-realtime.com', 'environment-example-b-fallback.ably-realtime.com' ]});
Whilst this is a Javascript example, all client SDKs offer the same options and should be identical apart from the language syntax and style.
3. Test your setup
We recommend you test all client SDKs can connect, publish and receive messages (where applicable) before rolling these changes out. Additionally, where possible, please inspect your client SDK traffic to ensure it is embedding the environment setting in the endpoint i.e. instead of connections to realtime.ably.io you should see [ENVIRONMENT]-realtime.ably.io now.
4. Confirm you are read and Ably can roll this into production
Once all your client library SDKs are using the new environment and traffic is arriving at our default endpoints, the team at Ably will be able to actively reroute your traffic based on the environment settings.
If you have regional constraints on your account, then please contact your customer success manager who will ensure the regional constraints are applied and tested too.