Version 0.9.0
Language EN

Multi-Machine

The goal of this document is to give you enough technical specifics to configure and run the Drone server in multi-machine mode. You will install the central Drone server and one or more agents.

The agents request builds from the central server, allowing you to scale your CI/CD infrastructure across multiple machines, operating systems and architectures. You should install one agent per-server.

Prerequisites

Provision a Server with a Public IP

Create your primary Drone server instance. This should be a Linux instance with modest resources (1GB RAM is fine). The Drone server exposes the website and API, and is responsible for scheduling and distributing workloads to agents.

This instance must be capable of receiving webhooks from GitHub. If your server is behind a firewall or does not have a public IP address (e.g. localhost) GitHub will be unable to deliver webhooks to your Drone instance.

Provision one or more Agent Servers

Create one or more agents servers. You will install a lightweight daemon on each agent server that is responsible for polling the central Drone server and executing pipelines. Pipelines are executed in ephemeral Docker containers, spawned on the host machine.

The following host machine architectures and operating systems are supported:

Create a GitHub OAuth Application

Create a GitHub oauth application. The Client ID and Client Secret are used to authorize access to GitHub resources. The Authorization callback URL must match the below format and path, and must use your exact server scheme and host.

http(s)://company.drone.com/login

If you do not know how to create an OAuth application, or are having difficulty configuring authorization, please see our tutorial.

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

Start the Server

The server container can be started with the below command. The container is configured through environment variables. For a full list of configuration parameters, please see the configuration reference.

docker run \
  --volume=/var/lib/drone:/data \
  --env=DRONE_TLS_AUTOCERT=true \
  --env=DRONE_GITHUB_CLIENT_ID=${DRONE_GITHUB_CLIENT_ID} \
  --env=DRONE_GITHUB_CLIENT_SECRET=${DRONE_GITHUB_CLIENT_SECRET} \
  --env=DRONE_RPC_SECRET=${DRONE_RPC_SECRET} \
  --env=DRONE_SERVER_HOST=${DRONE_SERVER_HOST} \
  --env=DRONE_SERVER_PROTO=https \
  --env=DRONE_LOGS_DEBUG=true \
  --publish=80:80 \
  --publish=443:443 \
  --restart=always \
  --detach=true \
  --name=drone \
  drone/drone:0.9.0-alpha.2

Start the Agent(s)

The agent container(s) can be started with the below command. The container is configured through environment variables. For a full list of configuration parameters, please see the configuration reference.

docker run \
  --volume=/var/run/docker.sock:/var/run/docker.sock \
  --env=DRONE_RPC_SERVER=${DRONE_RPC_SERVER} \
  --env=DRONE_RPC_SECRET=${DRONE_RPC_SECRET} \
  --env=DRONE_LOGS_DEBUG=true \
  --restart=always \
  --detach=true \
  --name=drone \
  drone/agent:0.9.0-alpha.2

If you are installing a Windows Server agent you need to change the --volume flag (above) to mount the Docker daemon named pipe:

docker run \
  --volume=//./pipe/docker_engine://./pipe/docker_engine
  --env=DRONE_RPC_SERVER=${DRONE_RPC_SERVER} \
  --env=DRONE_RPC_SECRET=${DRONE_RPC_SECRET} \
  --env=DRONE_LOGS_DEBUG=true \
  --restart=always \
  --detach=true \
  --name=drone \
  drone/agent:0.9.0-alpha.2

Server Reference

Environment

Configuration parameters are set using environment variables. This section defines a subset of recommended configuration paramters. For a full list, please see our configuration reference.

DRONE_GITHUB_CLIENT_ID

A string containing your GitHub oauth Client ID.

DRONE_GITHUB_CLIENT_ID=05136e57d80189bef462

DRONE_GITHUB_CLIENT_SECRET

A string containing your GitHub oauth Client Secret.

DRONE_GITHUB_CLIENT_SECRET=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_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_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=true

DRONE_LOGS_DEBUG

An boolean indicating DEBUG level logs should be written to stderr. The default log level is INFO and the default value is false.

DRONE_LOGS_DEBUG=true

Network

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

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

Agent Reference

Environment

Configuration parameters are set using environment variables. This section defines a subset of recommended configuration paramters. For a full list, please see our configuration reference.

DRONE_RPC_SERVER

Required string literal value provides your drone server address. The string must be a valid url.

DRONE_RPC_SERVER=http://drone.company.com

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_RUNNER_CAPACITY

An integer defining the maximum number of pipelines the agent should execute concurrently. The default value is two pipelines.

DRONE_RUNNER_CAPACITY=2

DRONE_LOGS_DEBUG

An boolean indicating DEBUG level logs should be written to stderr. The default log level is INFO and the default value is false.

DRONE_LOGS_DEBUG=true

Volumes

The agent requires access to your host machine Docker socket. This is used to launch pipelines in Docker containers on the host machine.

For linux agents mount the following socket:

--volume=/var/run/docker.sock:/var/run/docker.sock

For windows agents mount the following named pipe:

--volume=//./pipe/docker_engine://./pipe/docker_engine

On This Page:

Getting Help

Enterprise Support
Real-time chat support from the developers that wrote the code.
Mailing List
Search for information in the mailing list archives, or post a question.