Administer Bitbucket Data Center 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.
While working with Bitbucket on AWS, you can expand your environment by adding additional nodes, upgrade the existing nodes, or connect to them over SSH.
Connecting to your instance using SSH
You can perform node-level configuration or maintenance tasks on your deployment through the AWS Systems Manager Sessions Manager. This browser-based terminal lets you access your nodes without any SSH Keys or a Bastion host. For more information, see Getting started with Session Manager.
Access via Bastion host
You can also access your nodes via a Bastion host (if you deployed one). To do this, you'll need your SSH private key file (the PEM file you specified for the Key Name parameter). Remember, this key can access all nodes in your deployment, so keep this key in a safe place.
The Bastion host acts as your "jump box" to any instance in your deployment's internal subnets. That is, access the Bastion host first, and from there access any instance in your deployment.
The Bastion host's public IP is the BastionPubIp output of your deployment's ATL-BastionStack stack. This stack is nested in your deployment's Atlassian Standard Infrastructure (ASI). To access the Bastion host, use ec2-user as the user name, for example:
ssh -i keyfile.pem ec2-user@<BastionPubIp>
The ec2-user has sudo access. SSH access is by root is not allowed.
Configure SSL to enable HTTPS
To enhance Bitbucket's security, you should use a proper SSL certificate obtained from a reputable Certificate Authority (CA). See Securing Bitbucket in AWS for instructions on how to do this.
Backing up your instance
The Atlassian Bitbucket Server AMI includes a complete set of Bitbucket Server DIY Backup scripts which has been built specifically for AWS. For instructions on how to backup and restore your instance please refer to Using Bitbucket Server DIY Backup in AWS.
Upgrading
- Check if your apps are compatible with that version. Update your apps if needed. For more information about managing apps, see Using the Universal Plugin Manager.
- Enable integrity checks (if you haven't already).
We strongly recommend that you perform the upgrade first in a staging environment before upgrading your production instance. How to establish staging server environments for Bitbucket Server provides helpful tips on doing so.
Upgrading a Bitbucket Data Center on AWS involves three steps:
Step 1: Terminate all running Bitbucket Data Center application nodes
Set the number of application nodes used by the Bitbucket Data Center stack to 0. Then, update the stack.
Step 2: Update the version used by your Bitbucket Data Center stack
Set the number of application nodes used by Bitbucket Data Center to 1. Configure it to use the version you want. Then, update the stack again.
Step 3: Scale up the number of application nodes
You can now scale up your deployment to your original number of application nodes. For detailed instructions on how do to this, see Scaling up and down.
Stopping and starting your EC2 instance
An EC2 instance launched from the Atlassian Bitbucket Server AMI can be stopped and started just as any machine can be powered off and on again.
When stopping your EC2 instance, it is important to first
- Stop the
atlbitbucket,atlbitbucket_search, andpostgresql93services. - Unmount the
/media/atlfilesystem.
If your EC2 instance becomes unavailable after stopping and restarting
When starting your EC2 instance back up again, if you rely on Amazon's automatically assigned public IP address (rather than a fixed private IP address or Elastic IP address) to access your instance, your IP address may have changed. When this happens, your instance can become inaccessible and display a "The host name for your Atlassian instance has changed" page. To fix this you need to update the hostname for your Bitbucket Server instance.
To update the hostname for your Bitbucket Server instance
Restart the Bitbucket service on all application nodes by running this command, which will update the hostname
sudo service atlbitbucket restart- Wait for Bitbucket Server to restart.
- If you have also set up Bitbucket Server's Base URL to be the public DNS name or IP address be sure to also update Bitbucket Server's base URL in the administration screen to reflect the change.
Migrating your existing Bitbucket Server or Bitbucket Data Center instance into AWS
Migrating an existing instance to AWS involves moving consistent backups of your ${BITBUCKET_HOME} and your database to the AWS instance.
To migrate your existing instance into AWS
- Check for any known migration issues in the Bitbucket Data Center and Server Knowledge Base.
- Alert users to the forthcoming service outage.
- Create a user in the Bitbucket Server Internal User Directory with
SYSADMINpermissions to the instance so you don't get locked out if the new server is unable to connect to your User Directory. - Take a backup of your instance with either the Bitbucket Server Backup Client (Bitbucket Server only) or the Bitbucket Server DIY Backup (Bitbucket Server or Data Center).
- Launch Bitbucket Server in AWS using the Quick Start instructions, which uses a CloudFormation template.
- Connect to your AWS EC2 instance with SSH and upload the backup file.
- Restore the backup with the same tool used to generate it.
- If necessary, update the JDBC configuration in the ${
BITBUCKET_HOME}/shared/bitbucket.propertiesfile.
Resizing the data volume in your Bitbucket Server instance
By default, the application data volume in an instance launched from the Atlassian Bitbucket Server AMI is a standard Linux ext4 filesystem, and can be resized using the standard Linux command line tools.
To resize the data volume in your Bitbucket Server instance
- Stop the
atlbitbucket,atlbitbucket_search, andpostgresql93services. - Unmount the
/media/atlfilesystem. - Create a snapshot of the volume to resize.
- Create a new volume from the snapshot with the desired size, in the same availability zone as your EC2 instance.
- Detach the old volume and attach the newly resized volume as
/dev/sdf. - Resize
/dev/sdfusingresize2fs, verify that its size has changed, and remount it on/media/atl. - Start the
atlbitbucket,atlbitbucket_search, andpostgresql93services.
For more information, see Expanding the Storage Space of an EBS Volume on Linux, Expanding a Linux Partition, and the Linux manual pages for resize2fs and related commands.
Moving your Bitbucket Server data volume between instances
Occasionally, you may need to move your Bitbucket Server data volume to another instance–for example, when setting up staging or production instances, or when moving to an instance to a different availability zone.
There are two approaches to move your Bitbucket Server data volume to another instance
- Take a backup of your data volume with Bitbucket Server DIY Backup, and restore it on your new instance. See Using Bitbucket Server DIY Backup in AWS for this option.
Launch a new instance from the Atlassian Bitbucket Server AMI with a snapshot of your existing data volume.
A Bitbucket Server data volume may only be moved to a Bitbucket Server instance of the same or higher version than the original.
To launch a new instance from the Bitbucket Server AMI using a snapshot of your existing Bitbucket Server data volume
- Stop the
atlbitbucket,atlbitbucket_search, andpostgresql93services on your existing Bitbucket Server instance. - Unmount the
/media/atlfilesystem. - Create a snapshot of the Bitbucket Server data volume (the one attached to the instance as
/dev/sdf). - Once the snapshot generation has completed, launch a new instance from the Atlassian Bitbucket Server AMI as described in Launch Bitbucket in AWS manually. When adding storage, change the EBS volume device to
/dev/sdfas seen below and enter the id of the created snapshot.
- If the host name (private or public) that users use to reach your Bitbucket Server instance has changed as a result of moving availability zones (or as a result of stopping an instance and starting a new one) you will need to SSH in and run
sudo /opt/atlassian/bin/atl-update-host-name.sh<newhostname>
where <newhostname> is the new host name. - Once Bitbucket Server has restarted your new instance should be fully available.
- If the host name has changed you should also update the JDBC URL configuration in the
bitbucket.propertiesfile (typically located in/var/atlassian/application-data/bitbucket/shared/), as well as Bitbucket Server's base URL in the administration screen to reflect this.
Scaling up and down
To increase or decrease the number of application nodes:
- Sign in to the AWS Management Console, use the region selector in the navigation bar to choose the AWS Region for your deployment, and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/.
- Click the Stack name of your deployment. This will display your deployment's Stack info. From there, click Update.
- On the Select Template page, leave Use current template selected, and then choose Next.
- On the Specify Details page, go to the Cluster nodes section of Parameters. From there, set your desired number of application nodes in the following parameters:
- Minimum number of cluster nodes
- Maximum number of cluster nodes
- Click through to update the stack.
Disabled Auto Scaling
Since your cluster has the same minimum and maximum number of nodes, Auto Scaling is effectively disabled.
Setting different values for the minimum and maximum number of cluster nodes enables Auto Scaling. This dynamically scale the size of your cluster based on system load.
However, we recommend that you keep Auto Scaling disabled. At present, Auto Scaling can't effectively address sudden spikes in your deployment's system load. This means that you'll have to manually re-scale your cluster depending on the load.
Vertical VS horizontal scaling
Adding new cluster nodes, especially automatically in response to load spikes, is a great way to increase capacity of a cluster temporarily. Beyond a certain point, adding very large numbers of cluster nodes will bring diminishing returns. In general, increasing the size of each node (i.e., "vertical" scaling) will be able to handle a greater sustained capacity than increasing the number of nodes (i.e., "horizontal" scaling), especially if the nodes themselves are small. See Recommendations for running Bitbucket in AWS for more information.