Run your own Drone CI
Tags: droneci, cicd, devops, docker
Published: 2022-04-02 15:22:05

Started in 2012, [Drone CI](https://www.drone.io) is a container-native, event-based, multi-architecture, multi-OS platform for busy teams looking to tighten their software development lifecycles.

Since its [acquisition](https://www.prnewswire.com/news-releases/harness-acquires-continuous-integration-pioneer-droneio-and-commits-to-open-source-301106473.html) by [Harness](http://harness.io) in August of 2020, Drone CI has made significant improvements in usability and features. Let's see how, in just a few minutes, you can start experimenting with running Drone CI pipelines on any computer running [Docker](https://www.docker.com).

## Prerequisites

* Be comfortable running commands in the terminal
* [GitHub](https://github.com) account
* [ngrok](https://ngrok.com) account
* Computer that can run [amd64](https://en.wikipedia.org/wiki/X86-64) or [arm64](https://en.wikipedia.org/wiki/AArch64) [Docker](https://www.docker.com) containers (this includes the new [M1](https://en.wikipedia.org/wiki/Apple_M1)-based Macs)
  * In your terminal, verify you have `docker` and `docker-compose` commands available

## Overview

Drone CI supports multiple SCM solutions, such as [GitHub](https://github.com), [Bitbucket](https://bitbucket.org), [Gitea](https://gitea.io), [GitLab](https://gitlab.com) and [more](https://docs.drone.io/server/overview/).

This guide will focus on GitHub. Because we have chosen GitHub, we need to allow GitHub to send [webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks) to the Drone CI process on our computer. We will use [ngrok](https://ngrok.com) to create a [tunnel](https://en.wikipedia.org/wiki/Tunneling_protocol) to the internet so our Drone CI process can receive webhook traffic from GitHub.

## Create the `ngrok` tunnel

1. Login to [https://ngrok.com](https://ngrok.com)
2. Open [https://dashboard.ngrok.com/get-started/setup](https://dashboard.ngrok.com/get-started/setup), follow the steps to install the `ngrok` binary and connect to your account
3. Create the tunnel by running `ngrok http 8080` in your terminal, **do not stop the process** until you are finished with this guide
4. `ngrok` will create your tunnel and provide you with a URL such as `https://34f3-146-168-58-81.ngrok.io`

Your terminal should display session information similar to this screenshot:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wnujkee9w7v4zh83z0k9.png)

## Create the GitHub OAuth Application

1. Follow [Create an OAuth Application](https://docs.drone.io/server/provider/github/#create-an-oauth-application)
  - For the "Homepage URL", enter the `ngrok` URL from the previous step
  - For the "Authorization callback URL", enter the same `ngrok` URL, with `/login` appended
  - You will be given the "Client ID" and a "Client secret", make a note of each (the secret is only displayed once, if you misplace it, you will need to generate a new client secret)

Your OAuth application should look similar to this screenshot (for extra authenticity, upload the official Drone CI [logo](https://raw.githubusercontent.com/drone/brand/master/logos/png/dark/drone-logo-png-dark-256.png)):

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/huir37mtc7iobjod5hmn.png)

**Note:** `ngrok` URLs are temporary with the free plan. If you terminate your `ngrok` session and create a new one, your URL will change and you will need to update the "Homepage URL" and "Authorization callback URL" in your OAuth Application.

## Start the Drone and Drone Runner processes

The Drone [server](https://docs.drone.io/server/overview/) process requires at least one [runner](https://docs.drone.io/runner/overview/) process where pipelines will execute. Drone CI supports multiple runners, but the [Docker runner](https://docs.drone.io/runner/docker/overview/) is the most popular.

1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository [https://github.com/jimsheldon/drone-quickstart](https://github.com/jimsheldon/drone-quickstart) and [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) the forked repository to your computer
2. Edit the file `run.sh`
  - Set `DRONE_GITHUB_CLIENT_ID` and `DRONE_GITHUB_CLIENT_SECRET` using the "Client ID" and "Client secret" from the previous section
  - Set `DRONE_GITHUB_ADMIN` to your GitHub username
  - Set `DRONE_SERVER_HOST` to your `ngrok` URL, without the `https://` (if your `ngrok` URL is `https://34f3-146-168-58-81.ngrok.io`, set `DRONE_SERVER_HOST` to `34f3-146-168-58-81.ngrok.io`)
  - Save your changes
3. Open a new terminal session and change to the directory where you checked out the repository
  - Execute `run.sh` by typing `./run.sh` and hitting enter
  - Open your `ngrok` URL in a browser, you should be greeted with "**Welcome to Drone**"! 🎉
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/55ps00ib0bd09tej7904.png)
  - Click "Continue" and you will be asked to authorize your OAuth application
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s8w8udbu1bg6tin6mxxt.png)
  - Next you will see the "Complete your Drone Registration" screen
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s7snpuqe15njmni64qdp.png)
  - Click "Submit" and you will see the Drone CI interface, filter by "quickstart" to see your forked repository
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ck7olm1u2j5nimxdtghv.png)
  - Click on the repository, then click "Activate Repository"
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1mszaov5tf1xothsqlik.png)
  - Your repository should now be activated
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/78aith8gt0sqizcudp4k.png)

## Run your first pipeline

1. Edit the `.drone.yml` file in the root off your repository. Change the `echo hello world` message to something of your choice. If your CPU is amd64 (Intel, AMD) you should remove the `platform` section, which is currently specific to arm64 (Apple M1, Raspberry Pi)
2. [Push](https://github.com/git-guides/git-push) your change to a [branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) and open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
3. Your pull request will trigger a check in Drone CI called "continuous-integration/drone/pr"
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w3y44tsvhr92uje3qois.png)
4. Click the "Details" link, you will see your pipeline execution in Drone CI! Click the "hello" step to see your message printed
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mwcg424ks499plizhgw5.png)

You now have your very own [Drone CI Enterprise](https://www.drone.io/enterprise/) installation! Drone CI Enterprise includes a free trial of up to 5,000 builds. To learn more about licensing options, see the Drone CI [Enterprise FAQ](https://docs.drone.io/enterprise/).

The official Drone CI documentation provides example pipelines in [virtually every language](https://docs.drone.io/pipeline/docker/examples/). Try it out on one of your own projects!

## Teardown

1. In the directory where you ran `run.sh` run `docker-compose down`.
2. In the terminal where your `ngrok` session is running, type `CTRL-C`.

**Note:** `ngrok` URLs are temporary with the free plan. If you terminate your `ngrok` session, the next time you run `ngrok http 8080` your URL will change, and you will need to update the "Homepage URL" and "Authorization callback URL" in your GitHub OAuth Application, as well as the `DRONE_SERVER_HOST` value in `run.sh`.

## Conclusion

Hopefully this gives you a quick way to get started running Drone CI pipelines from your GitHub repositories.

If you would like to learn more and participate in the Drone CI and Harness communities, here are some helpful links:
- Official Drone CI documentation: https://docs.drone.io
- Harness Slack community: https://harnesscommunity.slack.com ([#drone](https://harnesscommunity.slack.com/archives/C028FPGCPF0) channel)
- Harness community forum: https://community.harness.io
- Harness & Drone User Group: https://www.meetup.com/harness/
- Drone CI official Twitter account: https://twitter.com/droneio