Secure Bitbucket in AWS
The AWS Quick Start template as a method of deployment is no longer supported by Atlassian. You can still use the template, 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.
AWS now recommends switching launch configurations, which our AWS Quick Start template uses, to launch templates. We won’t do this switch, however, as we’ve ended our support for the AWS Quick Start template. This means you're no longer able to create launch configurations using this template.
This page describes security best practices for running and maintaining Bitbucket in AWS.
Amazon Virtual Private Cloud (VPC) and Subnets
Amazon VPC enables you to launch AWS resources into a virtual network that you've defined. This virtual network closely resembles a traditional network that you'd operate in your own data center, with the benefits of using the scalable infrastructure of AWS. See Amazon EC2 and Amazon Virtual Private Cloud for more information.
A subnet is a range of IP addresses in your VPC. You can launch AWS resources into a subnet that you select. Use a public subnet for resources that must be connected to the internet, and a private subnet for resources that won't be connected to the internet.
See Amazon's article called Your VPC and Subnets for a general overview of VPCs and subnets.
To bolster the security of your VPC you may wish to enable one or more of the following:
- Secure your VPC with a firewall virtual appliance / AMI to defend against unauthorized network activity
- Configure a site-to-site VPN to ensure information is transferred securely between Bitbucket and its users
- Configure an intrusion prevention or intrusion detection virtual appliance to detect when unauthorized network activity has occurred
- Enable Amazon CloudTrail to log VPC API operations and keep an audit trail of network changes
Atlassian Standard Infrastructure
If you deployed Bitbucket through the AWS Quick Start, it will use the 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.
A security group acts as a virtual firewall that controls the traffic for one or more instances. The security group(s) that apply to newly launched instances depend on your launch method:
- If you launched instance(s) via the AWS console or API, the EC2 launch process gives you the opportunity to either create a new security group or associate one or more existing security group(s) with the instance. We recommend allowing inbound access to Bitbucket only on ports 22, 80, 443, and 7999, and only allowing access from the tightest possible IP address range.
- If launched via BitbucketServer.template or BitbucketDataCenter.template, AWS CloudFormation creates and manages a security group as part of the stack, allowing inbound access on ports 22, 80, 443, and 7999 from the Permitted IP range of addresses you specify. We recommend specifying the tightest possible Permitted IP range and not adding unnecessary inbound access to the security group after launch.
We recommend using security groups to restrict incoming traffic to your Bitbucket instance to the absolute minimum required.
See Amazon EC2 Security Groups for Linux Instances for more information.
Configure SSL to enable HTTPS
In order to enable HTTPS, you need a valid SSL certificate. SSL certificates are issued by a trusted third party Certificate Authority (CA), such as VeriSign, DigiCert or Thawte, which provide such services on a commercial basis. Atlassian does not provide such services.
Once you have a proper SSL certificate from a CA, you can import it to AWS Certificate Manager. This will enable you to use the certificate later on when deploying Bitbucket on AWS. To do that (for example, when deploying Bitbucket through the Quick Start), you'll need to provide the your certificate's Amazon Resource Number (ARN).
Until you install a valid SSL certificate, new Bitbucket Server and Data Center instances are configured to serve requests over plain HTTP, not HTTPS. This means all passwords and data will be sent unencrypted over the public internet (unless users are connected to AWS via a Virtual Private Gateway).
Load balancer settings with SSL enabled or disabled
When you deploy Bitbucket with SSL enabled, your load balancer's listeners will be set up as follows:
|Load Balancer Protocol
|Load Balancer Port
But if you didn't have an SSL certificate set up at initial launch time, your ELB will be configured with only one HTTP listener as follows:
|Load Balancer Protocol
|Load Balancer Port
Replace any self-signed SSL certificates (for Bitbucket Server)
When you use the Quick Start to deploy Bitbucket Data Center, you can supply a proper CA certificate to your deployment immediately at launch time. However, if you deploy Bitbucket Server via BitbucketServer.template (or manually as described in Launching Bitbucket in AWS manually), there is currently no way to install your own SSL certificate at initial launch time.
If you intend for your Bitbucket Server instance to be internet facing, we recommend setting
ATL_SSL_SELF_CERT_ENABLED=true to enable HTTPS to your instance at launch time. This setting will generate a self-signed certificate for your Bitbucket Server instance.
Self-signed certificates do not offer the same security as proper CA certificates. If your Bitbucket Server instance uses a self-signed certificate:
- most browsers will display security warnings that must be ignored before proceeding to the Bitbucket Server Web interface
- git clients will refuse to connect to Bitbucket Server over HTTPS unless configured to ignore the self-signed certificate with
git config --global http.sslVerify false
- application links and/or integrations with other applications that use Bitbucket Server's REST API and don't accept self-signed certificates may fail
Because of this, we recommend that you replace any self-signed SSL certificate with a proper CA certificate for your domain. To do this:
- Place your certificate file at (for example)
- Place your password-less certificate key file at
- Replace references to
- Replace references to
- Replace references to
- Append the contents of
/etc/nginx/ssl/my-ssl.crtto the default system PKI bundle (
/etc/pki/tls/certs/ca-bundle.crt) to ensure scripts on the instance (such as DIY backup) can
- Restart nginx.
Installing or changing your SSL certificate after deploying
When you deploy Bitbucket Data Center for the first time through the Quick Start, we recommend that you supply a proper CA certificate. To do this, you need to import your certificate to AWS Certificate Manager and then specify its Amazon Resource Number through the SSL Certificate ARN field.
If you didn't do this during deployment through the Quick Start (or if you used a self-signed certificate), you can still install or change your SSL certificate anytime after initial deployment:
- In the AWS console, go to Services > CloudFormation, select your stack, and click Update Stack.
- Specify your certificate's Amazon Resource Number (ARN) in the SSL Certificate ARN field. See Importing Certificates into AWS Certificate Manager for more information.
- Configure the HTTP to HTTPS redirect manually in the
bitbucket.propertiesfile, located in the
<Bitbucket home directory>/shareddirectory, as described in Redirect HTTP Requests to HTTPS.
Restart the Bitbucket service by running the following command on all application nodes
sudo service atlbitbucket restart
If the hostname of your Bitbucket instance has changed you will need to update Bitbucket's base URL as described in the page Specify the Bitbucket base URL.
Keeping your system up-to-date
It is essential to keep your Bitbucket Server instance up-to-date with patches and updates to maximize security and minimize opportunity for exploits and misadventure. On first boot a Bitbucket Server AMI instance will download the latest official release of Bitbucket Server at that time so you are assured of having the very latest version of Bitbucket Server when you first start using Bitbucket Server in AWS.
Amazon Linux Security Updates
The Bitbucket Server AMI is based on Amazon Linux and the latest version of this is used whenever we cut a new release of the Bitbucket Server AMI. Occasionally vulnerabilities in libraries and utilities used in Amazon Linux will be detected and updates posted in the Amazon Linux AMI yum repository. Atlassian will issue new versions of the Bitbucket Server AMI where necessary to ensure new Bitbucket Server AWS instances start with these updates but if you are managing an existing instance you may need to apply these updates yourself. By default, Amazon Linux applies all security updates on reboot. Alternatively you can run "yum update --security".
You may wish to apply other updates from the Amazon Linux AMI yum repository to your Bitbucket Server instance. You must ensure that any updated packages are supported by the version of Bitbucket Server you are running. Bitbucket Server version requirements can always be found on the Supported platforms page.
Bitbucket Server Updates
The Atlassian Bitbucket Server team have a strong release cadence and routinely issue releases including new features, performance and security fixes. It is strongly recommended you keep Bitbucket Server as up to date as possible. To update Bitbucket Server in an existing instance please follow the Bitbucket Server upgrade guide.