Prerequisites: set up the cluster

Before you begin, you must have set up a small-scale Hipchat Data Center instance or an Enterprise-scale Hipchat Data Center instance. (If you're using AWS with CloudFormation, use the instructions at Deploy Hipchat Data Center on AWS, and when you're done skip to the final setup steps.)

The setup process goes like this:

1. Configure the network for your deployment.
2. Deploy all of the component hosts required for your deployment.
3. Configure the component services so they're ready for Hipchat to use.

4. Deploy the Hipchat Data Center nodes. (You can find the link to the Hipchat binaries in the Release Notes.)

5. Get your license.
6. Configure the Hipchat nodes either using the setup wizard or using the configure CLI command.
7. Set up any optional features.

This page covers step 5 and 6, so make sure you haven't skipped anything!

Get your license

You'll need to have your license file handy to complete the Hipchat Data Center setup process. You don't need this immediately, but it's better to have it beforehand and be prepared! (If you're requesting a new evaluation license, see the instructions below.)

• If you've already got a Hipchat Data Center license, you're good to go! Just make sure you've downloaded the license key and have it ready for the next step. (You can find your current licenses at https://my.atlassian.com/license/)
• If you've got a legacy Hipchat Server license, you can reuse it for Hipchat Data Center. (You can download it from here, and you'll be upgraded to Data Center in your next renewal period. See the Hipchat Data Center FAQs for more information.) 

• If you're requesting a new evaluation license, you can wait until the last screen of the setup wizard and click Request an evaluation license. Clicking the link takes you to the request page and pre-fills the Server ID number for you. You can then finish filling out the request form, and download the license.

Configure Hipchat Data Center using the setup wizard

Once you've deployed the Hipchat Data Center nodes, you'll follow the configuration wizard steps to complete the configuration. 

1. Add one Hipchat node to your load balancer, and navigate to the web URL for your Hipchat service. The configuration wizard appears.
2. On the first screen, enter the Postgres configuration information.
   • the database address and port
   • the database name
   • the database user and the user's password
3. On the next screen, enter the Redis server and file storage information.
4. On the final screen, enter the details for your team. This includes:
   • your team name.
     This is your organization or team name, and will be the name of the chat server displayed to users.
   • the Hipchat base URL.
     This is the URL that users will connect to. This should be a Public DNS address, not a Public IP.
   • your Hipchat Data Center license key
5. Also on the final screen, enter the name and email address to use for the first administrator account for the deployment. Set a password for the administrator and click Finish.
6. The wizard exits and shows an "Administrator created" message and prompts you to log in as that administrator.
7. If you're deploying Hipchat for a large or highly-available deployment, configure the additional two nodes:
   1. Remove the first node from the load balancer. 
   2. Add one of the unconfigured nodes to the load balancer. 
   3. Navigate to the web URL for your Hipchat service. The setup wizard appears again, this time to configure the new node. 
   4. Enter the Postgres information for your deployment. The new node connects to the Postgres database and reads the configuration values you entered in the wizard previously.
   5. Remove the additional node from the load balancer, and repeat this process for the third node.
   6. Once you've configured the third node, add all nodes back to the load balancer, and continue to the next step. 

You're almost done! Next, you'll log in as an administrator to configure any optional Hipchat features your deployment requires.

Configure Hipchat Data Center using a config file

If you prefer to configure your Hipchat Data Center deployment from the terminal, you can create a configuration file, copy it to your Hipchat nodes, and then apply it to the nodes.

Use the JSON format template below, and substitute your deployment values for the template ones. The file includes the connection information for your external database, file store, and Redis cache. You'll enter your license key or evaluation license key using the web UI once the nodes are configured. 

1. Create a file called configuration.json.

2. Copy and paste the template below into the file.

   If you're deploying an instance earlier than version 3.1, the configuration file requires two additional keys: public-dns  and license. These are explained below.
   Example configuration.json file

   {
       "shared-storage-location": "filestorage.us-east-1.amazonaws.com:/",
       "redis-server": "10.10.10.5:6379",
       "redis-password": "foobarpassauthsecret",
       "database-server": "10.10.10.5:5432",
       "database-name": "hipchat_postgres",
       "database-user": "hipchat_user",
       "database-password": "super-secret-pw"
   }

3. Edit the file to replace the sample JSON values with the correct ones for your deployment.

   shared-storage-location	The IP or DNS entry of your NFS volume.
   redis-server	The address and port of your Redis cache. Use the default port 6379.
   redis-password	(Optional) The password for your Redis cache, if you changed it from the default password.
   database-server	The address and port used to access your Postgres instance. Use the default port 5432.
   database-name	The database name within the Postgres instance.
   database-user	The Postgres user that can access the database you listed in the previous line.
   database-passsword	The Postgres DB user password.
   If you're deploying Hipchat Data Center v 3.0.1 or earlier, the configuration file requires the following two additional keys.
   public-dns	The application's public URL or DNS entry, for example my-chatserver.example.com. This is the address that clients use to connect to your Hipchat Data Center instance. Use a DNS address (mostly letters with some numbers) rather than an IP address (all numbers).
   license	Your Hipchat Data Center license key.

4. Copy the configuration.json file to each Hipchat node in the cluster.

5. Connect to the first host over SSH. If you're using VMware hosts, connect as admin.

6. If you are deploying on VMware hosts, type  passwd  to reset or assign a password for the admin user. This is the node administrator password, not the Hipchat application administrator.

7. Apply the configuration file using the following command. Replace /path/to/configuration.json with the location of the configuration file on the host.

   hipchat datacenter configure --file /path/to/configuration.json

8. Run the following command to restart the node so that it runs using the configuration file you provided.

   hipchat datacenter restart

9. Once the node restarts, run the following command to run a diagnostic check.

    hipchat datacenter selfcheck 

10. If you are deploying an HA or Enterprise-scale cluster, repeat these steps for each of the Hipchat Data Center nodes you deployed.
11. Once you've set up your cluster and run the system check, add all of your Hipchat nodes to your load balancer.

12. Open your web browser, and go to the Hipchat administrative portal at  https://[your_full_hipchat_domain_name]/setup to complete the setup process. 

    If you're deploying Hipchat Data Center v 3.0.1 or earlier, go to https://[your_full_hipchat_domain_name]/sign_up  to create the administrator account. You'll then log in as the administrator to set the Team name.

13. From the web portal, set up the Hipchat instance URL and team name, enter your license key, and configure your application administrator account.

What's next?

Once you've configured the Hipchat Data Center nodes, you're almost done. 

1. Add the Hipchat Data Center node IPs to your load balancer if you haven't already done so. 
2. Configure the optional Hipchat features that you require for your deployment.