This article explains how to install the Drone server for Bitbucket Server, formerly known as Atlassian Stash. The server is packaged as a minimal Docker image distributed on DockerHub.
Create a Personal Access Token
Create a personal access token that is capable of cloning all repositories in the system. The token and associated username are used for all clone operations. We recommend creating a machine account for this purpose.
Navigate to the Personal Access Tokens page in the account settings, and click the Create Token button.
Create the personal access token. The creation form should indicate pull and clone access as pictured below. Click the Create button and copy the generated token.
Create a Key Pair
Create a key pair on your server. The key pair is used to setup an authentication provide with Bitbucket and authorize API access.
Generate the private key:
$ openssl genrsa -out /etc/bitbucket/key.pem 1024 Generating RSA private key, 1024 bit long modulus ....................................++++++ ..........++++++ e is 65537 (0x10001)
Generate a public key:
$ openssl rsa \ -in /etc/bitbucket/key.pem \ -pubout >> /etc/bitbucket/key.pub
Create an Application Link
Create a Bitbucket Application Link. The link will provide a Consumer ID and Private Key used to authorize access to Bitbucket resources. The Bitbucket application creation process is convoluted and error prone. Please bear with us.
Navigate the administrator panel and click the Application Links settings page. Enter your Drone server URL and click Create New Link.
Please fill out the form using the values specified below. Once complete click Continue to create your application.
- Set the application name to Drone
- Set the application type to Generic Application
- Set the provider name to Drone
- Set the consumer key to OauthKey
- Set the shared secret to any random alphanumeric value
- Set the request token url to your Drone server URL
- Set the access token url to your Drone server URL
- Set the authorize token url to your Drone server URL
Once the application is created it needs to be edited so that we can configure the Incoming Authentication. Please fill out the form using the values specified below and save your changes.
- Set the consumer key to OauthKey
- Set the consumer name to Drone
- Paste the contents of
/etc/bitbucket/key.pubin the public key textarea
- Leave Consumer Callback empty
- Leave Allow 2-Legged Oauth unchecked
Congratulations, you have made it through the most painful part of the installation. With luck, everything will work as expected and you will never have to do this again.
Create a Shared Secret
Create a shared secret to authenticate communication between runners and your central Drone server.
You can use openssl to generate a shared secret:
$ openssl rand -hex 16 bea26a2221fd8090ea38720fc445eca6
The Drone server is distributed as a lightweight Docker image. The image is self-contained and does not have any external dependencies. The latest tag will ensure the latest version of Drone.
$ docker pull drone/drone:2
The Drone server is configured using environment variables. This article references a subset of configuration options, defined below. See Configuration for a complete list of configuration options.
- Required string value set to username associated with the Personal Account token. This username is used to authenticate and clone all private repositories.
- Required string value set to your Personal Account Token. The token is used to authenticate and clone all private repositories.
- Optional boolean value configures Drone to authenticate when cloning public repositories. This should only be enabled when using GitHub Enterprise with private mode enable.
- Required string value configures your Bitbucket Server consumer key.
- Required string value configures the path to your Bitbucket Server private key file. Note that this file needs to also be mounted into the Drone server container as a volume.
- Required string value provides the Bitbucket Server address. For example
- Required string value provides the shared secret generated in the previous step. This is used to authenticate the rpc connection between the server and runners. The server and runner must be provided the same secret value.
- Required string value provides your external hostname or IP address. If using an IP address you may include the port.
- Required string value provides your external protocol scheme. This value should be set to http or https. This field defaults to https if you configure ssl or acme.
Start the Server
The server container can be started with the below command. The container is configured through environment variables. Remember to replace the placeholder values below with the appropriate values.
Once your server is up and running you will need to install runners to execute your build pipelines. See our runner installation documentation for detailed installation instructions.Install Runners