We offer nine clusters for Pusher apps, in the United States, Europe, South America and the Asia Pacific regions. You can read more about the release here or find about more about cluster configuration here.

It's only necessary to use these instructions if you need to transition a live application from one Pusher cluster to another without losing messages on any client.

The migration process involves multiple steps since clients may be connected to either cluster during the transition process.

Caveats

• It's currently not possible to migrate applications using presence channels while maintaining the same state on both sides. Depending on your application this may be acceptable for a short period.
• If you rely on channel existence WebHooks, you will need to ensure that you receive a `channel_vacated` webhook from both apps before determining that the channel no longer has any subscribers. You can verify which app sent the webhook by inspecting the `X-Pusher-Key` header. 
• If your application connects via a native client the transition period may be unfeasibly long due to the length of time it takes to roll out a new version to all your users.

We may address these shortcomings in future, please get in touch if they affect your app.

Transition process (using JS client)

1. From your account dashboard, create a new app in the cluster you wish to transition to.
2. Ensure the new app settings are configured to match the app settings of the old app. 
3. Ensure any webhooks are configured and that the batching setting is the same for the new app. 

4. Change your server code to publish to both the old cluster and the new cluster API endpoints.

   Taking the ruby gem as an example, you'd need to create a pusher client instance rather than using the global configuration:

   pusher_old = Pusher::Client.new({
     app_id: 'OLD_APP_ID',
     key: '...',
     secret: '...',
   })
   
   pusher_new = Pusher::Client.new({
     app_id: 'NEW_APP_ID',
     key: '...',
     secret: '...',
     cluster: 'eu',
   })

   Then trigger all your events on both clients.

5. Deploy the server change

6. Change the js configuration to connect to the new cluster

   var pusher = new Pusher('NEW_APP_KEY', {
         cluster: 'eu',
         forceTLS: true
       });

7. Deploy the client change

8. After waiting long enough for the js configuration change to propagate stop publishing to the old client. You can check whether clients are still connecting to your old app by checking the stats for that app in the Pusher Dashboard. 

Other things to consider

Collaborators will need to be added to the new app if in use. 

If you're using private channels

During the transition period you will receive channel auth requests for clients connected to both the old and new pusher apps. Channel auth requests must be signed with the appropriate app credentials, but unfortunately no information is provided in the channel auth request to indicate which app is being used.

The solution is to deploy server code which responds to auth requests on both the new and old endpoints, signing with the new or old client respectively.

In the JavaScript

authEndpoint: '/new_auth_endpoint'

On your server (Railsish example)

class AuthController < ApplicationController
  def your_existing_auth
    // Authenticate...
    response = pusher_old[params[:channel_name]].authenticate(params[:socket_id])
    render :json => response
  end

  def new_auth_endpoint
    // Authenticate...
    response = pusher_new[params[:channel_name]].authenticate(params[:socket_id])
    render :json => response
  end
end