On this page

Related content

Still need help?

This page describes administering a single-node instance of Bitbucket Server on AWS. For a deployment that is better suited to the architectural principles of AWS, we recommend deploying a clustered Bitbucket Data Center instance, which offers greater performance at scale, high availability and elastic scalability.

This page describes the Atlassian Bitbucket Amazon Machine Image (AMI), what's inside it, how to launch it, and how to perform administration tasks in the Amazon Web Services (AWS) environment.

The Bitbucket AMI

The Atlassian Bitbucket Server AMI provides a typical deployment of Bitbucket Server in AWS. It bundles all the components used in a typical Bitbucket Server deployment (reverse proxy, external database, backup tools, data volume, and temporary storage) pre-configured and ready to launch.

You can use the Atlassian Bitbucket Server AMI as a "turnkey" deployment of a Bitbucket Server instance in AWS, or use it as the starting point for customizing your own, more complex Bitbucket Server deployments.

On this page:

Components of the Bitbucket Server AMI

An instance launched from the Atlassian Bitbucket Server AMI contains the following components:

Bitbucket Server (either the latest version or a version of your choice),

manually using the AWS Console, which gives finer control over the optional components in the instance and AWS-specific network, security, and block device settings. For more info, see Launching Bitbucket Server in AWS manually.

On first boot, the Atlassian Bitbucket Server AMI reads the file /etc/atl (if any), which can override variables that enable each of the installed components. So for example to enable a self-signed SSL certificate, you can supply user data to the instance at launch time like this:

#!/bin/bash
echo "ATL_SSL_SELF_CERT_ENABLED=true" >>/etc/atl

UPDATE THESE

The following variables can be configured:

Variable name

Default value

Description

ATL_NGINX_ENABLED

true

Set to false to disable the Nginx reverse proxy, and leave Bitbucket Server's server.xml configured to listen on port 7990 with no proxy.

ATL_POSTGRES_ENABLED

true

Set to false to disable the PostgreSQL service, and leave Bitbucket Server configured with its internal H2 database.

ATL_SSL_SELF_CERT_ENABLED

false

Set to true to enable a self-signed SSL certificate to be generated at launch time, and for Bitbucket Server's server.xml and Nginx's nginx.conf to be configured for HTTPS.

It's highly recommended to replace this self-signed SSL certificate with a proper one for your domain, obtained from a Certification Authority (CA), at the earliest opportunity. See Securing Bitbucket in AWS. Once you have a true SSL certificate, install it as soon as possible.

To replace the self-signed SSL certificate with a true SSL certificate

Replace references to /etc/nginx/ssl/self-ssl.crt with /etc/nginx/ssl/my-ssl.crt

Replace references to /etc/nginx/ssl/self-ssl.key with /etc/nginx/ssl/my-ssl.key

Append the contents of /etc/nginx/ssl/my-ssl.crt to the default system PKI bundle (/etc/pki/tls/certs/ca-bundle.crt) to ensure scripts on the instance (such as DIY backup) can curl successfully.

Restart nginx.

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.

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

If necessary, update the JDBC configuration in the ${BITBUCKET_HOME}/shared/bitbucket.properties file.

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.

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

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 Launching Bitbucket Server in AWS manually. When adding storage, change the EBS volume device to /dev/sdf as 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 runsudo /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.properties file (typically located in /var/atlassian/application-data/bitbucket/shared/), as well as Bitbucket Server's base URL in the administration screen to reflect this.