Getting started with Bitbucket Data Center in AWS
The AWS Quick Start template as a method of deployment is nearing its end-of-support date on Feb 29, 2024. You can still use the template after this date but we won't maintain or update it.
We recommend deploying your Data Center products on a Kubernetes cluster using our Helm charts for a more efficient and robust infrastructure and operational setup. Learn more about deploying on Kubernetes
This page provides an overview of the options available for running self-managed Bitbucket Data Center and Bitbucket Server instances on Amazon Web Services.
Running Bitbucket on Amazon Web Services (AWS) gives you scalable computing capacity without the need to invest in hardware up front, while retaining control over where and how your code is hosted within your organisation.
To this end, Atlassian provides:
- an AWS Quick Start which deploys a clustered Bitbucket Data Center in a matter of minutes, using AWS best practices for security and availability
- an Amazon CloudFormation template that can be customised for different deployment needs while keeping the process automated
- an Amazon Machine Image (AMI) that can be used for running Bitbucket Server on EC2 as an application server building block in more heavily customised deployments
- tools and guidelines for manually deploying, backing up, restoring, sizing, and administering Bitbucket Server and Bitbucket Data Center instances on AWS
Non-clustered VS clustered environment
A single node is adequate for most Small or Medium size deployments, unless you need specific features that require clustering (for example, high availability).
The Quick Start provides two deployment options, each with its own template. The first option deploys the Atlassian Standard Infrastructure (ASI) and then provisions Bitbucket Data Center into this ASI. The second option only provisions Bitbucket Data Center on an existing ASI.
Atlassian Standard Infrastructure (ASI)
The ASI is a virtual private cloud (VPC) that contains the components required by all Atlassian Data Center applications. For more information, see Atlassian Standard Infrastructure (ASI) on AWS.
Here's an overview of the architecture deployed by the AWS Quick Start for Bitbucket Data Center:
The deployment consists of the following components:
- Instances/nodes: One or more Amazon Elastic Cloud (EC2) instances as cluster nodes, running Bitbucket.
- Load balancer: An Amazon Elastic Load Balancer (ELB), which works both as load balancer and SSL-terminating reverse proxy.
- Database: Your choice of shared database instance – Amazon RDS or Amazon Aurora.
- Storage: A shared NFS server to store repositories in a common location accessible to all Bitbucket nodes.
- Amazon CloudWatch: Basic monitoring and centralized logging through Amazon's native CloudWatch service.
- An Amazon OpenSearch Service domain for code and repository search.
For more information on the architecture, components and deployment process, see our Quick Start Guide.
Advanced customizations
All of our AWS Quick Starts use Ansible playbooks to configure specific components of your deployment. These playbooks are available publicly on this repository:
https://bitbucket.org/atlassian/dc-deployments-automation
You can override these configurations by using Ansible variables. Refer to the repository’s README file for more information.
Launching the Quick Start from your own S3 bucket (recommended)
The fastest way to launch the Quick Start is directly from its AWS S3 bucket. However, when you do, any updates we make to the Quick Start templates will propagate directly to your deployment. These updates sometimes involve adding or removing parameters from the templates. This could introduce unexpected (and possibly breaking) changes to your deployment.
For production environments, we recommend that you copy the Quick Start templates into your own S3 bucket. Then, launch them directly from there. Doing this gives you control over when to propagate Quick Start updates to your deployment.
- Clone the Quick Start templates (including all of its submodules) to your local machine. From the command line, run:
git clone --recurse-submodules https://github.com/aws-quickstart/quickstart-atlassian-bitbucket - (Optional) The Quick Start templates repository uses the directory structure required by the Quick Start interface. If needed (for example, to minimize storage costs), you can remove all other files except the following:
quickstart-atlassian-bitbucket├─ submodules│ └─ quickstart-atlassian-services│ └─ templates│ └── quickstart-vpc-for-atlassian-services.yaml└─ templates├── quickstart-bitbucket-dc-with-vpc.template.yaml└── quickstart-bitbucket-dc.template.yaml Install and set up the AWS Command Line Interface. This tool will allow you to create an S3 bucket and upload content to it.
Create an S3 bucket in your region:
aws s3 mb s3://<bucket-name> --region <AWS_REGION>
At this point, you can now upload the Quick Start templates to your own S3 bucket. Before you do, you'll have to choose which Quick Start template you’ll be using:
quickstart-bitbucket-dc-with-vpc.template.yaml: use this for deploying into a new ASI (end-to-end deployment).quickstart-bitbucket-dc.template.yaml: use this for deploying into an existing ASI.
- In the template you’ve chosen, the
QSS3BucketNamedefault value is set toaws-quickstart. Replace this default with the name of your S3 bucket. Go into the parent directory of your local clone of the Quick Start templates. From there, upload all the files in local clone to your S3 bucket:
aws s3 cp quickstart-atlassian-bitbucket s3://<bucket-name> --recursive --acl public-read- Once you’ve uploaded everything, you’re ready to deploy your production stack from your S3 bucket. Go to Cloudformation → Create Stack. When specifying a template, paste in the Object URL of the Quick Start template you’ll be using.
Amazon Aurora database for high availability
The Quick Start also allows you to deploy Bitbucket Data Center with an Amazon Aurora clustered database (instead of RDS).
If the writer fails, Aurora automatically promotes one of the readers to take its place. For more information, see Amazon Aurora Features: PostgreSQL-Compatible Edition.
For instructions on manually setting up a new Amazon Aurora clustered database and connecting it to Bitbucket Data Center, see Configuring Bitbucket Data Center to work with Amazon Aurora. Amazon Aurora is supported on Bitbucket Data Center 6.7 and up.
Amazon CloudWatch for basic monitoring and centralized logging
By default, Amazon CloudWatch will also collect and store logs from each node into a single, central source. This centralized logging allows you to search and analyze your deployment's log data more easily and effectively. See Analyzing Log Data with CloudWatch Logs Insights and Search Log Data Using Filter Patterns for more information.
Amazon CloudWatch provides basic logging and monitoring, but also costs extra. To help reduce the cost of your deployment, you can disable logging or turn off Amazon CloudWatch integration during deployment.
To download your log data (for example, to archive it or analyze it outside of AWS), you’ll have to export it first to S3. From there, you can download it. See Exporting Log Data to Amazon S3 for details.
Auto Scaling groups
If you can identify any periods of high and low load, you can schedule the application node cluster to scale accordingly. See Scheduled Scaling for Amazon EC2 Auto Scaling for more information.
To study trends in your organization's load, you'll need to monitor the performance of your deployment. Refer to Bitbucket Data Center sample deployment and monitoring strategy for tips on how to do so.
Customizing the AWS Quick Start's CloudFormation templates
To get you up and running as quickly as possible, the Quick Start doesn't allow the same level of customization as a manual installation. Alternatively, you can customize the CloudFormation templates used by the Quick Start to fit your needs. These templates are available from the following repository:
https://github.com/aws-quickstart/quickstart-atlassian-Bitbucket
Even though you can deploy our Data Center products on AWS GovCloud, we don’t test or verify our AWS Quick Starts on the AWS GovCloud environment and can’t provide any support.
Administering Bitbucket Data Center in AWS
See Administering Bitbucket Data Center in AWS for information about performing administration tasks on a Bitbucket instance within AWS, including:
- configuring variables when launching Bitbucket in AWS
- maintaining, resizing, upgrading, migrating, and customizing your Bitbucket deployment in AWS
- additional details about the components within the Bitbucket Server AMI
Securing Bitbucket within AWS
AWS is accessed over the public Internet, so it is important to apply appropriate security measures when running Bitbucket Server in AWS. See Best practices for securing Bitbucket in AWS for security guidance on a range of security topics, including Amazon Virtual Private Cloud (VPC), Security Groups, and SSL.
Performance guidelines
To get the best performance out of your Bitbucket deployment in AWS, it's important not to under-provision your instance's CPU, memory, or I/O resources. Whether you choose to deploy Bitbucket Data Center, which offers performance gains via horizontal scaling, or a single node Bitbucket Server instance, we have specific recommendations on choosing AWS EC2 and EBS settings for best performance per node.
If you are using the CloudFormation template, these settings are already included. Otherwise, see Infrastructure recommendations for enterprise Bitbucket instances on AWS.
Mirroring
Smart Mirroring can drastically improve Git clone speeds for distributed teams working with large repositories. For an overview of the benefits to mirroring, see Mirrors. The Bitbucket Data Center FAQ also answers many common questions about smart mirroring (and mirroring in general).
For detailed instructions, see Set up a mirror.