How to use the Drone One-Click Application Image
DigitalOcean's Drone One-Click application image provides an easy way to set up a continuous integration solution on a server under your control. This tutorial will guide you through the steps of creating a new Drone droplet and configuring it to work with your existing github repositories.
Step One - Create a drone.io Droplet
To get started with a new droplet running drone.io simply create a droplet specifying your hostname and size.
Select the region where you want to create your new droplet.
Select Drone on Ubuntu 14.04 from the Applications tab.
If you use ssh keys to log into your droplets you can specify a key here.
Now click create to begin the creation of your new droplet.
Step Two - Prepare Github
Now that our droplet is being created, we need to enable access to our GitHub accounts via oAuth. We'll be generating a pair of tokens to be used in drone's configuration.
We need to generate these values from your GitHub account. Click here to go to the appropriate settings page on GitHub, called Applications.
Click the Register new application button on the upper right. This will bring up a new form to fill out:
Add your Application name. The Homepage URL should be http://YOUR_DROPLET_IP/. Add your Application description.
IMPORTANT: Make sure the Authorization callback URL is set to http://YOUR_DROPLET_IP/api/auth/github.com in order to authenticate properly!
Once you're set with that, click Register application to be brought to the new application's information page.
You'll need two bits of information from here, the Client ID and Client Secret. (Keep the Client Secret actually secret! This is NOT something you should share with anyone!)
These tokens will be used to authorize our own Drone application to add webhooks to any GitHub repository we add to Drone via the Dashboard panel. The webhooks will trigger on every new commit we push to GitHub, and this will cause Drone to clone the new changes and run the build.
Make note of these tokens, as we will need them in the next step.
Step Three - Configure Drone Settings
Log into your new droplet using an ssh client. If you are not using ssh key based authentication you will be prompted to provide a new root password.
You will then be presented with a prompt asking you to configure drone.io. Press Enter to continue and you will be asked what type of repository you are connecting.
Drone Configuration ------------------- This script will set up the initial configuration for your new drone installation. More details on configuring drone can be found here: http://readme.drone.io/setup/config/settings/ If you choose not to configure drone at this time you will need to configure it manually by editing the /etc/drone/drone.toml file manually. Would you like to continue with automatic configuration? (Y/n)
Press 1 to choose Github and press Enter.
Select a code repository ------------------------ 1. Github 2. Github Enterprise 3. Bitbucket 4. Gitlab Select one (1-4) and press Enter
When prompted, enter your Client ID and Client Secret from Step Two.
Github Configuration -------------------- You must register your application with GitHub in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click Register new application. Please use /api/auth/github.com as the Authorization callback URL path. Additional information is available here: http://readme.drone.io/setup/config/github/ Client ID: YOURCLIENTID Secret: YOURSECRET
Configure SMTP (optional)
You will now be prompted to configure SMTP. This step is required if you wish to receive email notifications related to your builds.
SMTP Configuration ------------------ SMTP configuration for Drone. This is required if you plan to send email notifications for build statuses. Do you want to set up SMTP at this time? (y/N)
If you select (Y)es you will be prompted for additional details about your SMTP server and account. If you select (N)o you will be taken to the next step.
Host: smtp.example.com Port: 25 From: email@example.com User: firstname.lastname@example.org Pass: mypassword
You will now be asked if you want to enable open registration. If you do not choose to allow open registration, each user account will need to be added manually to drone.
Open Registration ----------------- Open Registration allows users to self-register for Drone. This is recommended if Drone is being hosted behind a firewall. When false, the system admin will need to manually add users to Drone through the admin screens. Open Registration (T/f)?
Your new settings are now written to the file /etc/drone/drone.toml where you can edit them further if needed.
Step Four - Adding your Repository
Now we are ready to set up drone with your initial account. Navigate to
http://YOUR_DROPLET_IP/login. You should see a login page like the one below:
We only see Github listed here because this is the service we set up earlier. Now click on the GitHub button, then the Authorize application button to start the login and sync process.
This is the main dashboard for Drone, you can see the three most recent repositories in your GitHub account, and expand the list by clicking BROWSE ALL. If all of your repos do not appear, simply click SYNC in the upper right hand corner.
Feel free to explore the dashboard.
Next we need to allow access to your various Git repository sources.
Step Five - Run Builds from Github
Find the name of the repository you'd like to add to Drone CI and select it. This will activate Drone and add webhooks to your repository.
After activation, you will see the blank repository status page:
You can explore some of the more advanced settings for repository using the button in the upper right corner.
The .drone.yml file
We need to make a new file in the repository called `
.drone.yml. This will command Drone and tell it how to build and test the code in the GitHub repository. Here is a very simple file we will use to test if Drone is set up properly.
image: dockerfile/nginx script: - echo hello world
imagedefines the base image we are pulling from (the image can be from the public Docker registry, a private registry, or locally built). In this case we are using an Nginx image.
scriptsimply defines the commands that Drone should execute, and in what order. You can define more than one script command with another -
<command here>on a new line. (Make sure the tabs line up!)
This script just echoes "hello world" to prove that Drone is working. It doesn't actually test anything about your code.
In a real build and test scenario, you'd want to have Drone use a Docker image that matches your production environment, and you'd want the scripts to test the code in the repository.
Now, commit your
.drone.yml file to your repository. This commit, and any other commits you make in the future (to any file, not just the
.drone.yml file), will trigger the webhook Drone placed in your repository. Drone should now be hard at work pulling the base image, and running your build scripts!
Drone will detect the new commit, clone any changes made to the code, and follow the instructions defined in the .drone.yml file. It will display a notification on the bottom of the page to let you know the build is running, click it to see the build status page.
The build will take a few minutes as Drone needs to pull the image from the Docker public registry.
If the build passes, you can click on the commit to see more details. You should see output similar to the following:
$ git clone --depth=50 --recursive --branch=master git://github.com/captainshar/dronetest.git /var/cache/drone/src/github.com/captainshar/dronetest $ git checkout -qf 9908588ae4e4abcba8afb5029baad5c49a835ba4 $ echo hello world hello world $ exit 0
You might also see a few warnings related to Perl; that's fine.
If you completed all these steps and your build passes, you now have your own personal Drone.io worker ready to build and test almost any language-based project!
Drone also supports Bitbucket and GitLab, and the setup processes using OAuth are relatively the same as Github's. To add another service you will need to edit your /etc/drone/drone.toml file to add the appropriate settings:
DRONE_BITBUCKET_CLIENT DRONE_BITBUCKET_SECRET DRONE_GITLAB_URL ...
Then you can restart drone to have your changes take effect with:
service drone restart
Now that you have Drone ready to run builds, you can modify the
.drone.yml to do some more advanced testing.
For example, if you wanted to test a Node application using a test framework such as Karma or Mocha, you can change the
image section to the official node
image, and change the script section to execute npm and run the tests! Take a look around the Docker registry for images that might suit your application.
If you want to get really fancy, you can look into something called Drone Wall to provide a display board of all your build statuses.
Have fun commanding your Drone!