Skip to main content

Your First Drone Installation and Build

By August 20, 2020November 1st, 2023Blog, Community

Contributed by Ravi Lachhman

drone by harness logo with a jedi chicken

Drone Architecture

Drone has a Server to Runner model. A Server orchestrates the runners which perform the tasks. 

Graphic of how the Server to Runner model works. SCM to Drone server to Ephemerial Runners (accessed via Shared Secrets) to Container Registry

The Drone Server authenticates with your SCM provider and then via a shared secret communicates with the Runners. Wiring up these pieces are pretty simple. 

Let’s Get Started 

In this example, the moving pieces will be a GitHub Account, a running CentOS machine, a Kubernetes Cluster, and a Docker Hub account. Like always, you can follow along in the blog and/or watch the video. The example GitHub repository can be cloned/forked before this example at


GitHub / SCM Prep

The Drone Server needs to authenticate with your SCM provider. This is accomplished in GitHub by making an OAuth application. This is done by navigating to Settings ➡ Developer settings ➡ OAuth Apps + Register a new application. 

screenshot of the No OAuth applications page

When you register a new OAuth application, you will need to have the DNS/IP address of the Drone Server handy. In my case, this is The callback URL has /login appended to the Homepage URL. 

Screenshot of the filled in OAuth application form

When you register the application, make sure to note the Client ID and Client Secret, which will be needed to wire the Drone Server. 

Screenshot of a client ID and client Secret
CentOS Drone Prep

Depending on where you get CentOS from, you might have to install Docker Engine. Assuming that you have Docker Engine installed, the only piece of prep you need on the server before installing is to generate the shared secret which will be used for Server to Runner communication. Make sure to copy down the shared secret. 

openssl rand -hex 16

Screenshot of command line run: openssl rand -hex 16

Drone Installation

To get Drone on your machine, simply run a Docker Pull on the image. 

sudo docker pull drone/drone:1

screenshot command line run sudo docker pull drone/drone:1

Once pulled, you can configure the properties for Docker Run. The properties to fill in for barebones are the secrets and server address and protocol. Let’s go ahead and create an admin user. The admin user follows your GitHub username. 

screenshot create admin user
sudo docker run \
  --volume=/var/lib/drone:/data \
  --env=DRONE_GITHUB_CLIENT_ID=yourClientID \
  --env=DRONE_GITHUB_CLIENT_SECRET=yourClientSecret \
  --env=DRONE_RPC_SECRET=yourRPCSecret \
  --env=DRONE_SERVER_PROTO=http \
  --env=DRONE_USER_CREATE=username:yourGitHubUser,admin:true \
  --publish=80:80 \
  --publish=443:443 \
  --restart=always \
  --detach=true \
  --name=drone \
Drone UI

One issuing the Docker Run commands with the properties, you can head to the IP or DNS entry of your Drone server. In my case, navigate to You will be greeted to authorize your user via GitHub. 

Authorize your GitHub Credentials.

screenshot of GitHub authorize drone credentials

Once Authorized, Drone will build a list of repositories. 

screenshot of an empty repo list
screenshot of filled repo list

Now you are ready to deploy runners, in this case, Kubernetes. 

Kubernetes Cluster Prep

In this example, we will leverage the Kubernetes Runners. For the Kubernetes Runners to request resources on your behalf, a Role Binding is needed as well as the Runner Deployment. 

A simple approach is to build out two YAML files, one for the Role and Role Binding and another for the Deployment. 

screenhot of YAML file code

kubectl apply -f drone_role.yaml

screenshot of command line run code kubectl apply -f drone_role.yaml

In the Runner Deployment Spec, make sure to update the Drone Server, Shared Secret, and Protocol to match your installation. 

screenshot runner deployment specs

When the items are filled in, can deploy the Deployment. 

kubectl apply -f drone_deployment.yaml

screenshot deploy deployment

Optionally you can validate that the Runner is connected to the Server. Get the Pod Name then run a log command. 

kubectl get pods –all-namespaces

screenshot run log command kubectl get pods --all-namespaces

kubectl logs drone-6564db8f9f-949s2 -c runner

screenshot log command kubectl logs drone-6564db8f9f-949s2 -c runner

Success! Now would be time to start marching towards your first build. 

Marry the CI and SCM Together

Drone leverages Configuration as Code to describe pipelines. Drone can work off of webhook requests from the Source Code Management solution to orchestrate when a new build needs to be kicked off. 

Prep the Repository 

Can leverage the Drone UI to “Activate” the Repository. In my “firstdrone” repository,  the webhooks are empty. 

screenshot of the GitHub empty webhooks page

In the Drone UI, navigate to your repository of choice and then Active Repository. 

screenshot of the repo drone settings page

For this example, the defaults are fine for the Repository Activation. The configuration to modify if needed is the name of the Drone Configuration file to monitor. In this example, you will monitor for “Drone.yaml” in the repository.  

screenshot of config menu where you type in "Drone.yaml" in the Configuration field

Then you can validate that the webhook has been successfully created in GitHub. 

screenshot of GitHub webhooks page with new hook

With the CI and SCM wirings out of the way, the next steps are to define your first pipeline and fire off a build. 

Your First Drone Project

If starting with an empty repository you can leverage a simple example of a project structure or wire together your own project/repository.  

screenshot of GitHub project structure including: Dockerfile, Drone.yaml, LISCENSE, and main.go

If following this example, you wired into Drone to watch out for “Drone.yaml”. Drone’s declarative pipeline format is easy to craft and understand as per the example. In the example pipeline, we leverage the Docker Plugin for the publish setting and will be downloaded automatically during execution time. 

screenshot of Drone.yaml file including the docker plugin code

The highlighted lines are leveraging secrets to wire in my Docker Hub credentials. You need to update the repo location to your own and create Drone Secrets to wire in. 

Back in the Drone UI, navigate to the repository settings, and add the needed secrets. 

drone menu secrets page, adding docker

Add the appropriate secrets to match the format of the example.

screenshot of docker secrets showing the secrets name matching the name assigned in the docker.yaml file

With those wirings out of the way, you are now ready to kick off your first build and publish it to Docker Hub. 

Your First Build and Publish

With the wirings out of the way, all that is left is to commit the “Drone.yaml” with some sort of change and you are off to the races. 

screenshot of commit change on GitHub

Once you hit Commit changes, the CI magic starts, and your build and publish are off!

screenshot the build and publish page in Drone

Success! Congratulations on your first Drone build and publish!

screenshot of successful Drone build

Validating success on Docker Hub.  Enjoy the spoils of your hard work and don’t forget to check out Drone

screenshot of docker hub showing the successful build