Deploy Hipchat Data Center on AWS

If you're deploying Hipchat on Amazon Web Services (AWS), you can use these instructions to quickly provision and configure a highly-available deployment using AWS's CloudFormation template language. The template sets up hosts and services, configures their network, installs the Hipchat Data Center AMIs, and connects the cluster.  You can then connect to the cluster to configure optional features. 

You can learn more about CloudFormation in the official CloudFormation documentation.

tip/resting Created with Sketch.

This template creates a highly-available Enterprise-scale deployment with three Hipchat nodes. If you're familiar with CloudFormation, you can modify the template to meet your organization's needs. However we can only guarantee support for the template as provided.

On this page:

How it works

AWS's CloudFormation is a templating language that allows you to build a "stack," in which specific servers and services are deployed and linked together with minimum amount of input from you. When you create a stack using the Hipchat Data Center CloudFormation template, AWS performs the following steps:

  1. Creates a VPC that the cluster will live in, and any standard VPC facilities, such as the bastion host (or jumpbox).
  2. Creates, deploys, and configures a Postgres 9.5 instance using AWS Relational Database Service (RDS).
    • Creates the hipchat_postgres database.
    • Creates the hipchat_user database user.
    • Grants the hipchat_user GRANTS ALL access to the hipchat_postgres database.
  3. Creates, deploys, and configures a Redis cache using AWS ElastiCache, and configures it.
  4. Creates, deploys, and configures an AWS Elastic File System (EFS) storage volume.
  5. Creates, deploys, and configures an AWS Elastic Load Balancer (ELB).
  6. Creates three Hipchat Data Center nodes from AMIs, and performs the following configuration steps:
    • Applies a standard configuration that connects the nodes to the external services.
    • Adds the three nodes to the load balancer.
    • Restarts the cluster to apply the configuration changes.
  7. Installs your SSL certificate on the load balancer so it can terminate SSL traffic.

Prerequisites

  • A Hipchat Data Center license key (You'll use this once the cluster is running)
  • An Amazon Web Services account with CloudFormation enabled 
    • You must use one of the following regions:
      • eu-west-1 (Ireland)
      • eu-central-1 (Frankfurt)
      • us-east-1 (N. Virginia)
      • us-west-2 (Oregon)
      • ap-southeast-2 (Sydney)
    • You must deploy the nodes across three or more Availability Zones within the same region.
    • The region you deploy to must support EFS.
  • A SSL certificate for the DNS domain you will use, uploaded to AWS' certificate manager 
  • SSH keypair on the AWS region you're going to use (so you can administer the cluster)

Deploy

  1. In your browser, navigate to the Amazon CloudFormation portal.
  2. Click Create Stack.
  3. On the screen that appears, choose Specify an Amazon S3 template URL.
  4. Paste the Hipchat Data Center CloudFormation template URL in the field below
    https://s3.amazonaws.com/hipchat-server-stable/dc/production/templates/quickstart-hipchat-master.template

  5. On the next screen, enter values for the following fields.

    URL

    Enter the fully qualified domain name that clients will use to access the deployment. Do not include the http or https protocol prefix, for example:

    hipchat.example.com
    DNS zone (optional)

    If you are using AWS Route53 for DNS, enter your Route53 zone name . Route53 zone name domains must end with a trailing period, for example:

     example.com.

    If you are not using Route53, you must create your own DNS entry that directs to the Hipchat Data Center load balancer's A record.

    SSL Certificate NameSelect the Amazon Resource Name (ARN) of the the SSL certificate you uploaded to AWS. The CN must match the hostname.domain-name you provided. (You can see your list of SSL certificates at the Amazon console: https://console.aws.amazon.com/acm/home. Select a certificate, and the ARN is displayed at the bottom of the Details section.)
    SSH KeyPairSelect the SSH KeyPair you will use to access the deployment. You must have already created or imported this KeyPair in your AWS Console, in the AWS Region you will use.
  6. Optionally, override the advanced configuration options as needed. 

    Dedicated VPC network addressThe network address to use for Hipchat Data Center in your Virtual Private Cloud.
    Whitelisted IP rangeThe CIDR IP range that is allowed to access the Hipchat service.
    RDS database userWe recommend that you set the RDS username to hipchat, but if you must use a different name, enter that one here.
    RDS database passwordChange this from the default password. Use between 16 and 24 ASCII characters, and include both uppercase and lowercase letters, digits, and at least one symbol (#%^&+=!).
    Bastion host SSH access rangeEnter the CIDR IP range used by administrators for SSH access to the cluster's jumpbox.
  7. Double check your entries, and click Next.
  8. Optionally, enter any tags for your AWS Resources, then click Next.
  9. Review your entries, and if they look correct, click Create.

    If you are troubleshooting a CloudFormation based deployment, you might want to select "disable rollback". See the AWS Cloud Formation troubleshooting guide for more information.


    AWS will take about an hour to fully deploy the Hipchat Data Center Cluster. 

  10. Once the deployment is finished, browse to your server's full host name and the setup path (for example https://hipchat.example.com/setup).
    The wizard prompts you for the name of your Team, your license, and the details for the owner account for the instance. (You'll use the owner account to configure optional features in the next step.)

Configure optional features

Although the CloudFormation template configures trust and networking between the nodes and the storage services, it does not enable or disable optional Hipchat services (for example email notifications or video chat) which you might want on your deployment.

Before you add users, follow the instructions at Configure optional Hipchat Data Center features to make sure your deployment has all the functionality they will expect.

Quick deploy known issues

The AWS CloudFormation Quick Start has the following known issues:

  • If you reboot a host, it can cause the Elastic LoadBalancer to misidentify it as "unhealthy" and terminate it. The Auto Scaling Group (ASG) then launches another instance. 
  • If deployment fails with a CREATE_FAILED message, your AWS environment may have a misconfiguration or another underlying problem. Check the system logs on your EC2 instance for error messages before contacting Atlassian Support. 

Connect to AWS Hipchat Data Center nodes

The Hipchat Data Center node instances are deployed in a Virtual Private Cloud (a type of private network). To SSH to them, you need to SSH into the bastion host (also called a jumpbox) to access the private network. From there, with either the SSH private key on that jumpbox or SSH Agent forwarding, you can SSH to the nodes using their private IP addresses.

tip/resting Created with Sketch.

The BastionHostIP output in the CloudFormation stack is the IP of the jumpbox. 

Last modified on Dec 20, 2017

Was this helpful?

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