Version 1.0.0
Language EN

Multi-Machine

The goal of this document is to give you enough technical specifics to configure and run the Drone in multi-machine mode. Once you complete this guide you will need to install one or many agents.

Prerequisites

Create a Shared Secret

Create a shared secret to authenticate communication between agents and your central Drone server. This shared secret is passed to both the server and agents using the DRONE_RPC_SECRET environment variable.

You can use openssl to generate a shared secret:

$ openssl rand -hex 16
bea26a2221fd8090ea38720fc445eca6

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.

stash_token_list

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.

stash_token_create

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 OAuth Application

Create a Bitbucket OAuth application. The Consumer ID and Private Key are 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.

stash_application_link

Please fill out the form using the values specified below. Once complete click Continue to create your application.

stash_application_link_create

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.

stash_application_link_edit

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.

Download the Server

The Drone server is distributed as a lightweight Docker image. The image is self-contained and does not have any external dependencies.

docker pull drone/drone:1.0.0-rc.1

Start the Server

The server container can be started with the below command. The container is configured through environment variables.

$ docker run \
  --volume=/etc/bitbucket/key.pem:/etc/bitbucket/key.pem \
  --volume=/var/lib/drone:/data \
  --env=DRONE_GIT_ALWAYS_AUTH=false \
  --env=DRONE_GIT_PASSWORD={% your-personal-token %} \
  --env=DRONE_GIT_USERNAME={% your-personal-token-username %} \
  --env=DRONE_RPC_SECRET={% your-shared-secret %} \
  --env=DRONE_STASH_SERVER={% your-bitbucket-server-address %} \
  --env=DRONE_STASH_CONSUMER_KEY=OauthKey \
  --env=DRONE_STASH_PRIVATE_KEY=/etc/bitbucket/key.pem \
  --env=DRONE_SERVER_HOST={% your-drone-server-hostname %} \
  --env=DRONE_SERVER_PROTO={% your-drone-server-protocol %} \
  --env=DRONE_TLS_AUTOCERT=false \
  --publish=80:80 \
  --publish=443:443 \
  --restart=always \
  --detach=true \
  --name=drone \
  drone/drone:1.0.0-rc.1

Server Reference

This section provides additional explanation of the configuration variables used earlier in this document. This represents a subset of configuration parameters. Please see the configuration reference for a complete list.

DRONE_RPC_SECRET

Required string literal value provides the drone shared secret. This is used to authenticate the rpc connection to the server. The server and agent must be provided the same secret value.

DRONE_RPC_SECRET=9c3921e3e748aff725d2e16ef31fbc42

DRONE_STASH_SERVER

A string contianer your Bitbucket Server address.

DRONE_STASH_SERVER=https://stash.domain.com

DRONE_STASH_CONSUMER_KEY

A string containing your Bitbucket Server consumer key.

DRONE_STASH_CONSUMER_KEY=OauthKey

DRONE_STASH_PRIVATE_KEY

A string containing 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.

DRONE_STASH_PRIVATE_KEY=/etc/bitbucket/key.pem

DRONE_GIT_ALWAYS_AUTH

Boolean value configures Drone to authenticate when cloning public repositories. This is only required when your source code management system (e.g. GitHub Enterprise) has private mode enabled.

DRONE_GIT_ALWAYS_AUTH=false

DRONE_GIT_USERNAME

String literal value set to username associated with the Personal Account token. This username is used to authenticate and clone all private repositories.

DRONE_GIT_USERNAME=janecitizen

DRONE_GIT_PASSWORD

String literal value set to your Personal Account Token. The token is used to authenticate and clone all private repositories.

DRONE_GIT_PASSWORD=7c229228a77d2cbddaa61ddc78d45e

DRONE_SERVER_PROTO

A string containing your Drone server protocol scheme. This value should be set to http or https. This field defaults to https if you configure ssl or acme.

DRONE_SERVER_PROTO=https

DRONE_SERVER_HOST

A string containing your Drone server hostname or IP address.

DRONE_SERVER_HOST=drone.domain.com

DRONE_TLS_AUTOCERT

An boolean indicating debug level logs should be use for automatic SSL certification generation and configuration. The default value is false.

DRONE_TLS_AUTOCERT=false

Docker Reference

Publish

The server listens on standard http and https ports inside the container, which should be published on the host machine:

--publish=80:80
--publish=443:443

Volumes

Mount the Data Volume

The server creates a sqlite database and persists to a contianer volume at /data. To prevent dataloss, we recommend mounting the data volume to the host machine when using the default sqlite database.

--volume=/var/lib/drone:/data

Mount the Private Key

The server requires access to your Bitbucket Server private key. This should be mounted as a volume. The container mount path must match the path specified in DRONE_STASH_PRIVATE_KEY.

--volume=/etc/bitbucket/key.pem:/etc/bitbucket/key.pem

On This Page:

Getting Help

Mailing List
Search for information in the mailing list archives, or post a question.
Chat Support
Real-time chat support from maintainers and community members.