Migrate from Hipchat Server to Hipchat Data Center

If you previously used Hipchat Server, and are ready to migrate to a Hipchat Data Center deployment, use this guide and the Hipchat Data Center deployment guides to set up your new deployment and migrate users.

On this page:

A note for large Hipchat Server deployments

If you are migrating from a Hipchat Server instance with more than 5 million messages, you'll need to use a separate Hipchat migration tool we developed to speed up large-scale migrations. You should also Contact Hipchat Data Center Support before you start, so we can help you plan your migration.

If your Hipchat Server instance contains fewer than 5 million messages, carry on!

How do I find out how many messages I have? (Click for instructions)

Hipchat Server tracks how many messages have been sent on your deployment on the Status page in the Server admin section. However, retention settings and message deletion can make this number inaccurate.

To get an accurate message count, connect to the Hipchat Server deployment and run a script.

  1. Connect to the Hipchat Server deployment (with the admin account), using your terminal or shell.
  2. Copy the script below to the server.
    You can either create the file locally as message_counter.sh and then use scp to copy the file to the Hipchat Server machine, or you can create a new file directly on the Hipchat Server machine and then paste the script contents into the file.

    message_counter.sh
    #!/bin/bash
    # This script counts the message entries directly from the database
    # 06-21-17
    # Must run inside Hipchat Server command line interface
    
    counts=$(curl 'localhost:9200/_cat/indices?v' | awk 'FNR > 1 {print $6}')
    
    total=0
    
    for number in $counts
    do
       total=$(($total+$number))
    done
    
    echo "Total messages: $total"
  3. Once you have the script on the server, make it executable using the following command:
    chmod +x message_counter.sh

  4. Finally, execute (run) the script using the following command:
    ./message_counter.sh

The script runs and returns the number of messages in your deployment. If it's over 5 million, contact Support.

Before you begin

Hold your horses!  Before you do anything:

  1. Read the architecture information, and decide how you will deploy Hipchat Data Center.
    Hipchat Data Center is currently available for deployment on VMware and AWS only, however you can now deploy it either with a single Hipchat node, or with a three-Hipchat-node cluster for scale or higher availability. Regardless of how many Hipchat nodes you deploy, you also need to provide the external data stores for the service and manage SSL termination within your network.
  2. Plan your deployment.
    Use the information in the per-deployment scale Set Up Guides to determine what component servers and services you need in order to deploy.
    (warning) The requirements guide also includes important sizing information, so don't skip it!
  3. Read the full deployment guide to understand the deployment process, and check the release notes for your destination version.
    The release notes will alert you if you need to do anything special before you deploy.
  4. Deploy and test on an evaluation instance first.
    We don't need to tell you this, it's just a good practice. 


  5. Deploy your production Hipchat Data Center cluster. 
    Head's up, you can only import an archive into an empty cluster. You should plan to take notes during your evaluation, and either reinstall using those notes, or use the snapshots tip below to reset your cluster. 

    A Pro Tip if you're comfortable using snapshots...
    tip/resting Created with Sketch.

    If you want to reuse a test cluster for production, make sure that it is provisioned appropriately for your final deployment scale, and take a snapshot of all nodes, services, and data stores in their empty state.

    Because you can only import a Hipchat data archive into an empty cluster, this will help you restore the cluster to a good state to run the import and become a production instance.

  6. Schedule an outage or maintenance window for your deployment.
    Although we designed the upgrade process to minimize downtime for your deployment, you should do this just in case.

How do I choose a Hipchat Data Center scale?

Previously, Hipchat Server provided hardware-based recommendations depending on how many users your deployment serves. These recommendations no longer make sense due to the changes in architecture for Hipchat Data Center. Instead, there are currently two supported deployment options, and your organization will fall under one of two sizes depending on the number of users the deployment will serve, and the scale of the database. 

If you have...Use...
1-100 userssmall scale deployment
101-500 users
500-1000 users

You can use either a small-scale or an Enterprise-scale deployment, depending on your organization's needs.

(You might want to contact Hipchat Support for help deciding.)

1001-3000 users
3000-5000 usersEnterprise scale deployment
5000 users or more


Deploy a Hipchat Data Center cluster

  1. Choose the Deployment option that best serves your organization. 
  2. Use either the Enterprise-scale Set Up guide or the Small-scale Set Up guide to deploy and configure the required components and services.
  3. Configure the Hipchat nodes.
  4. Finally, configure your instance's optional features.

Be sure to verify that the deployment is up and running, and that the database and file store are working correctly before proceeding.

Export your Hipchat Server data

  1. Export the data from your production Hipchat Server instance.

  2. Make a list of the integrations and API tokens on your old Hipchat Server instance. (You'll re-enable and reconfigure them on the new Hipchat Data Center instance once it's set up.)

    An exported Hipchat archive does not include the integrations on your Hipchat Server instance, emoticons, any passwords or API tokens, any users' room auto-join information, or server settings.


Prepare the Hipchat Data Center deployment

  1. Verify that the destination Hipchat Data Center cluster is up and functioning correctly. All external data stores must be configured before you import your data archive.
  2. Run the sudo dont-blame-hipchat command. (This allows you to write to the file store in the next step.)
  3. Copy the data archive file to the NFS host and put it in the /file_store/shared directory .

Import the archive

  1. Import the data archive into your Hipchat Data Center deployment.
  2. Restore the integrations (now called add-ons) and API tokens that you were using in Hipchat Server.

Connect to a external authentication sources or import users

If your organization uses an external authentication source (such as Active Directory, LDAP, Crowd, or a SAML identity provider such as Okta or OneLogin), connect your new Hipchat Data Center instance to that source or provider after you import the data from your old server.

See the instructions for external directories (LDAP, Active Directory, Crowd and Jira) and SAML providers for more details.

Verify the deployment

Test your deployment to make sure that all of the functionality is working as intended. You should confirm that:

  • if you are connecting to an authentication source, the users you expect are included in the Hipchat user list
  • users can log in using your organization's authentication source
  • users can view (and if enabled, edit) their profile information
  • users can send and receive messages in chat rooms
  • emoticons are working in chat messages
  • any integrations that are enabled are working
  • users can upload and view files
  • users can search for messages in their chat history
  • if enabled, users can send and receive 1-to-1 chats
  • if enabled, video chat is working

Notify and let your users in

Once you've confirmed that the new Hipchat Data Center deployment is up and running, tell your users and let them log in!  Woohoo!

Last modified on Jan 30, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.