mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-05-20 09:18:15 +00:00
Code Issues Projects Releases Wiki Activity

Readme

Browse source
This commit is contained in:
Laszlo Fogas 2019-07-05 15:30:25 +02:00
parent fb4c337c4b
commit c6326bdd19
19 changed files with 2603 additions and 116 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
.drone.sh
View file

@ -1,27 +1,8 @@
#!/bin/sh
# only execute this script as part of the pipeline.
# [ -z "$CI" ] && echo "missing ci environment variable" && exit 2
# only execute the script when github token exists.
# [ -z "$SSH_KEY" ] && echo "missing ssh key" && exit 3
# write the ssh key.
# mkdir /root/.ssh
# echo -n "$SSH_KEY" > /root/.ssh/id_rsa
# chmod 600 /root/.ssh/id_rsa
# add github.com to our known hosts.
# touch /root/.ssh/known_hosts
# chmod 600 /root/.ssh/known_hosts
# ssh-keyscan -H github.com > /etc/ssh/ssh_known_hosts 2> /dev/null
# clone the extras project.
set -e
set -x
# git clone git@github.com:drone/drone-enterprise.git extras
# build a static binary with the build number and extra features.
go build -ldflags '-extldflags "-static" -X github.com/laszlocph/drone-oss-08/version.VersionDev=build.'${DRONE_BUILD_NUMBER} -o release/drone-server github.com/laszlocph/drone-oss-08/cmd/drone-server
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-X github.com/laszlocph/drone-oss-08/version.VersionDev=build.'${DRONE_BUILD_NUMBER} -o release/drone-agent github.com/laszlocph/drone-oss-08/cmd/drone-agent
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags '-X github.com/laszlocph/drone-oss-08/version.VersionDev=build.'${DRONE_BUILD_NUMBER} -o release/linux/arm64/drone-agent github.com/laszlocph/drone-oss-08/cmd/drone-agent

81
LICENSE
View file

@ -1,80 +1,3 @@
The Drone Community Edition (the "Community Edition") is licensed under the
Apache License, Version 2.0 (the "Apache License"). You may obtain a copy of
the Apache License at
Drone-OSS-08 is Apache 2.0 licensed with the source files in this repository having a header indicating which license they are under and what copyrights apply.
http://www.apache.org/licenses/LICENSE-2.0
The Drone Enterprise Edition (the "Enterprise Edition") is licensed under
the Drone Enterprise License, Version 1.1 (the "Enterprise License"). A copy
of the Enterprise License is provided below.
The source files in this repository have a header indicating which license
they are under. The BUILDING file provides instructions for creating the
Community Edition distribution subject to the terms of the Apache License.
-----------------------------------------------------------------------------
Licensor: Drone.IO, Inc
Licensed Work: Drone Enterprise Edition
Additional Use Grant: Usage of the software is free for entities with both:
(a) annual gross revenue under (USD) $1 million
(according to GAAP, or the equivalent in its country
of domicile); and (b) less than (USD) $5 million in
aggregate debt and equity funding.
Change Date: 2022-01-01
Change License: Apache-2.0
Notice
The Drone Enterprise License (this document, or the "License") is not an Open
Source license. However, the Licensed Work will eventually be made available
under an Open Source License, as stated in this License.
-----------------------------------------------------------------------------
Drone Enterprise License 1.1
Terms
The Licensor hereby grants you the right to copy, modify, create derivative
works, redistribute, and make non-production use of the Licensed Work. The
Licensor may make an Additional Use Grant, above, permitting limited
production use.
Effective on the Change Date, or the fourth anniversary of the first publicly
available distribution of a specific version of the Licensed Work under this
License, whichever comes first, the Licensor hereby grants you rights under
the terms of the Change License, and the rights granted in the paragraph
above terminate.
If your use of the Licensed Work does not comply with the requirements
currently in effect as described in this License, you must purchase a
commercial license from the Licensor, its affiliated entities, or authorized
resellers, or you must refrain from using the Licensed Work.
All copies of the original and modified Licensed Work, and derivative works
of the Licensed Work, are subject to this License. This License applies
separately for each version of the Licensed Work and the Change Date may vary
for each version of the Licensed Work released by Licensor.
You must conspicuously display this License on each original or modified copy
of the Licensed Work. If you receive the Licensed Work in original or
modified form from a third party, the terms and conditions set forth in this
License apply to your use of that work.
Any use of the Licensed Work in violation of this License will automatically
terminate your rights under this License for the current and all other
versions of the Licensed Work.
This License does not grant you any right in any trademark or logo of
Licensor or its affiliates (provided that you may use a trademark or logo of
Licensor as expressly required by this License).
TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
TITLE.
Files under the `docs/` folder is licensed under Creative Commons Attribution-ShareAlike 4.0 International Public License. It is a derivative work of the https://github.com/drone/docs git repository.

331
README.md
View file

@ -1,31 +1,326 @@
## Yes, it's a fork
# Drone-OSS-08
This repository is a hard fork of the Drone CI system.
An opinionated fork of the Drone CI system.
Forked at the `0.8.9` version https://github.com/drone/drone/commit/768ed784bd74b0e0c2d8d49c4c8b6dca99b25e96
- Based on the v0.8 code tree
- Focused on developer experience.
## Why fork?
[![Build Status](https://cloud.drone.io/api/badges/laszlocph/drone-oss-08/status.svg)](https://cloud.drone.io/laszlocph/drone-oss-08) [![Go Report Card](https://goreportcard.com/badge/github.com/laszlocph/drone-oss-08)](https://goreportcard.com/report/github.com/laszlocph/drone-oss-08) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
Drone has been an open-core project since many prior versions. With each source file indicating whether it is part of the Apache 2.0 licensed or the propritary enterprise license. In the 0.8 line the enterprise features were limited to features like autoscaling and secret vaults.
![Drone-OSS-08](docs/drone.png)
However in the 1.0 line, databases other than SQLite, TLS support and agent based horizontal scaling were also moved under the enterprise license. Limiting the open source version to single node, hobbyist deployments.
## Table of contents
The above feature reductions and the lack of clear communication of what is part of the open-source version led to this fork.
- [About this fork](#about-this-fork)
- [Motivation](#motivation)
- [The focus of this fork](#the-focus-of-this-fork)
- [Who uses this fork](#who-uses-this-fork)
- [Pipelines](#pipelines)
- [Getting started](#getting-started)
- [Pipeline documentation](#pipeline-documentation)
- [Plugins](#plugins)
- [Custom plugins](#custom-plugins)
- [Server setup](#server-setup)
- [Quickstart](#quickstart)
- [Authentication](#authentication)
- [Database](#database)
- [SSL](#ssl)
- [Metrics](#metrics)
- [Behind a proxy](#behind-a-proxy)
- [Contributing](#contributing)
- [License](#license)
## The focus of this fork
## About this fork
The focus of this fork is
#### Motivation
- Github
- Kubernetes and VM based backends
- Linux/amd64
- Some really good features that Drone 1.0 introduced: multiple pipelines, cron triggers
Why fork? See my [motivation](docs/motivation.md)
## Why should you use this fork?
#### The focus of this fork
you shouldn't necessarily. Paying for Drone 1.0 is a fine choice.
This fork is not meant to compete with Drone or reimplement its enterprise features in the open.
Check the issues and releases of this project if you are evaluating this project.
Also you can check the devlog to get the nuances: https://laszlo.cloud/drone-oss-08-devlog-1
Instead, I'm taking a proven CI system - that Drone 0.8 is - and applying a distinct set of product ideas focusing on:
The project is currently used by one user, with 50+ repos and 500+ builds a week.
- UI experience
- the developer feedback loop
- documentation and best practices
- tighter Github integration
- Kubernetes backend
with less focus on:
- niche git systems like gitea, gogs
- computing architectures like arm64
- new pipeline formats like jsonnet
#### Who uses this fork
Currently I know of one organization using this fork. With 50+ users, 130+ repos and more than 300 builds a week.
## Pipelines
#### Getting started
Place this snippet into a file called `.drone.yml`
```yaml
pipeline:
build:
image: debian:stable-slim
commands:
- echo "This is the build step"
a-test-step:
image: debian:stable-slim
commands:
- echo "Testing.."
```
The pipeline runs on the Drone CI server and typically triggered by webhooks. One benefit of the container architecture is that it runs on your laptop too:
```sh
$ drone exec --local
stable-slim: Pulling from library/debian
a94641239323: Pull complete
Digest: sha256:d846d80f98c8aca7d3db0fadd14a0a4c51a2ce1eb2e9e14a550b3bd0c45ba941
Status: Downloaded newer image for debian:stable-slim
[build:L0:0s] + echo "This is the build step"
[build:L1:0s] This is the build step
[a-test-step:L0:0s] + echo "Testing.."
[a-test-step:L1:0s] Testing..
```
Pipeline steps are commands running in container images.
These containers are wired together and they share a volume with the source code on it.
#### Pipeline documentation
See all [pipeline features](docs/usage/pipeline.md).
## Plugins
Plugins are Docker containers that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more.
Example pipeline using the Docker and Slack plugins:
```yaml
pipeline:
backend:
image: golang
commands:
- go get
- go build
- go test
docker:
image: plugins/docker
username: kevinbacon
password: pa55word
repo: foo/bar
tags: latest
notify:
image: plugins/slack
channel: developers
username: drone
```
#### Custom plugins
Plugins are Docker containers with their entrypoint set to a predefined script.
[See how an example plugin can be implemented in a bash script](docs/usage/bash_plugin.md).
## Server setup
#### Quickstart
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start the Drone server with a single agent. It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
Each agent is able to process one build by default. If you have 4 agents installed and connected to the Drone server, your system will process 4 builds in parallel. You can add more agents to increase the number of parallel builds or set the agent's `DRONE_MAX_PROCS=1` environment variable to increase the number of parallel builds for that agent.
```yaml
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
volumes:
- drone-server-data:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
drone-agent:
image: drone/agent:{{% version %}}
command: agent
restart: always
depends_on:
- drone-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
volumes:
drone-server-data:
```
Drone needs to know its own address. You must therefore provide the address in `<scheme>://<hostname>` format. Please omit trailing slashes.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
- DRONE_OPEN=true
+ - DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
```
Drone agents require access to the host machine Docker daemon.
```diff
services:
drone-agent:
image: drone/agent:{{% version %}}
command: agent
restart: always
depends_on: [ drone-server ]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Drone agents require the server address for agent-to-server communication.
```diff
services:
drone-agent:
image: drone/agent:{{% version %}}
command: agent
restart: always
depends_on: [ drone-server ]
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
+ - DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
```
Drone server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
+ - DRONE_SECRET=${DRONE_SECRET}
drone-agent:
image: drone/agent:{{% version %}}
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_DEBUG=true
+ - DRONE_SECRET=${DRONE_SECRET}
```
Drone registration is closed by default. This example enables open registration for users that are members of approved GitHub organizations.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
+ - DRONE_OPEN=true
+ - DRONE_ORGS=dolores,dogpatch
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
```
Drone administrators should also be enumerated in your configuration.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
- DRONE_OPEN=true
- DRONE_ORGS=dolores,dogpatch
+ - DRONE_ADMIN=johnsmith,janedoe
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
```
#### Authentication
Authentication is done using OAuth and is delegated to one of multiple version control providers, configured using environment variables. The example above demonstrates basic GitHub integration.
See the complete reference for [Github](docs/administration/github.md), [Bitbucket Cloud](docs/administration/bitbucket.md), [Bitbucket Server](docs/administration/bitbucket_server.md) and [Gitlab](docs/administration/gitlab.md).
#### Database
Drone mounts a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
See the [database settings](docs/administration/database.md) page to configure Postgresql or MySQL as database.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
+ volumes:
+ - drone-server-data:/var/lib/drone/
restart: always
```
#### SSL
Drone supports ssl configuration by mounting certificates into your container.
See the [SSL guide](docs/administration/ssl.md).
Automated [Lets Encrypt](docs/administration/lets_encrypt.md) is also supported.
#### Metrics
A [Prometheus endpoint](docs/administration/lets_encrypt.md) is exposed.
#### Behind a proxy
See the [proxy guide](docs/administration/proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
## Contributing
Drone-OSS-08 is Apache 2.0 licensed and accepts contributions via GitHub pull requests.
[How to build the project]()
## License
Drone-OSS-08 is Apache 2.0 licensed with the source files in this repository having a header indicating which license they are under and what copyrights apply.
Files under the `docs/` folder is licensed under Creative Commons Attribution-ShareAlike 4.0 International Public License. It is a derivative work of the https://github.com/drone/docs git repository.

1
docs/LICENSE Normal file
View file

@ -0,0 +1 @@
Files in this folder are licensed under Creative Commons Attribution-ShareAlike 4.0 International Public License. It is a derivative work of the https://github.com/drone/docs git repository.

70
docs/administration/bitbucket.md Normal file
View file

@ -0,0 +1,70 @@
Drone comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Drone container using the following environment variables:
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_BITBUCKET=true
+ - DRONE_BITBUCKET_CLIENT=95c0282573633eb25e82
+ - DRONE_BITBUCKET_SECRET=30f5064039e6b359e075
- DRONE_SECRET=${DRONE_SECRET}
drone-agent:
image: drone/agent:{{% version %}}
restart: always
depends_on:
- drone-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
```
# Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_BITBUCKET=true
: Set to true to enable the Bitbucket driver.
DRONE_BITBUCKET_CLIENT
: Bitbucket oauth2 client id
DRONE_BITBUCKET_SECRET
: Bitbucket oauth2 client secret
# Registration
You must register your application with Bitbucket in order to generate a client and secret. Navigate to your account settings and choose OAuth from the menu, and click Add Consumer.
Please use the Authorization callback URL:
```nohighlight
http://drone.mycompany.com/authorize
```
Please also be sure to check the following permissions:
```nohighlight
Account:Email
Account:Read
Team Membership:Read
Repositories:Read
Webhooks:Read and Write
```
# Missing Features
Merge requests are not currently supported. We are interested in patches to include this functionality. If you are interested in contributing to Drone and submitting a patch please [contact us](https://discourse.drone.io).

133
docs/administration/bitbucket_server.md Normal file
View file

@ -0,0 +1,133 @@
Drone comes with experimental support for Bitbucket Server, formerly known as Atlassian Stash. To enable Bitbucket Server you should configure the Drone container using the following environment variables:
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_STASH=true
+ - DRONE_STASH_GIT_USERNAME=foo
+ - DRONE_STASH_GIT_PASSWORD=bar
+ - DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
+ - DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
volumes:
+ - /path/to/key.pem:/path/to/key.pem
drone-agent:
image: drone/agent:{{% version %}}
restart: always
depends_on:
- drone-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
```
# Private Key File
The OAuth process in Bitbucket server requires a private and a public RSA certificate. This is how you create the private RSA certificate.
```nohighlight
openssl genrsa -out /etc/bitbucket/key.pem 1024
```
This stores the private RSA certificate in `key.pem`. The next command generates the public RSA certificate and stores it in `key.pub`.
```nohighlight
openssl rsa -in /etc/bitbucket/key.pem -pubout >> /etc/bitbucket/key.pub
```
Please note that the private key file can be mounted into your Drone conatiner at runtime or as an environment variable
Private key file mounted into your Drone container at runtime as a volume.
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_STASH=true
- DRONE_STASH_GIT_USERNAME=foo
- DRONE_STASH_GIT_PASSWORD=bar
- DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
- DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
+ volumes:
+ - /etc/bitbucket/key.pem:/etc/bitbucket/key.pem
```
Private key as environment variable
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_STASH=true
- DRONE_STASH_GIT_USERNAME=foo
- DRONE_STASH_GIT_PASSWORD=bar
- DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA_STRING=contentOfPemKeyAsString
- DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
```
# Service Account
Drone uses `git+https` to clone repositories, however, Bitbucket Server does not currently support cloning repositories with oauth token. To work around this limitation, you must create a service account and provide the username and password to Drone. This service account will be used to authenticate and clone private repositories.
# Registration
You must register your application with Bitbucket Server in order to generate a consumer key. Navigate to your account settings and choose Applications from the menu, and click Register new application. Now copy & paste the text value from `/etc/bitbucket/key.pub` into the `Public Key` in the incoming link part of the application registration.
Please use http://drone.mycompany.com/authorize as the Authorization callback URL.
# Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_STASH=true
: Set to true to enable the Bitbucket Server (Stash) driver.
DRONE_STASH_URL
: Bitbucket Server address.
DRONE_STASH_CONSUMER_KEY
: Bitbucket Server oauth1 consumer key
DRONE_STASH_CONSUMER_RSA
: Bitbucket Server oauth1 private key file
DRONE_STASH_CONSUMER_RSA_STRING
: Bibucket Server oauth1 private key as a string
DRONE_STASH_GIT_USERNAME
: Machine account username used to clone repositories.
DRONE_STASH_GIT_PASSWORD
: Machine account password used to clone repositories.

48
docs/administration/database.md Normal file
View file

@ -0,0 +1,48 @@
This guide provides instructions for using alternate storage engines. Please note this is optional. The default storage engine is an embedded SQLite database which requires zero installation or configuration.
# Configure MySQL
The below example demonstrates mysql database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples.
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
+ DRONE_DATABASE_DRIVER: mysql
+ DRONE_DATABASE_DATASOURCE: root:password@tcp(1.2.3.4:3306)/drone?parseTime=true
```
# Configure Postgres
The below example demonstrates postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples.
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
environment:
+ DRONE_DATABASE_DRIVER: postgres
+ DRONE_DATABASE_DATASOURCE: postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
```
# Database Creation
Drone does not create your database automatically. If you are using the mysql or postgres driver you will need to manually create your database using `CREATE DATABASE`
# Database Migration
Drone automatically handles database migration, including the initial creation of tables and indexes. New versions of Drone will automatically upgrade the database unless otherwise specified in the release notes.
# Database Backups
Drone does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice.
# Database Archiving
Drone does not perform data archival; it considered out-of-scope for the project. Drone is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably.

78
docs/administration/github.md Normal file
View file

@ -0,0 +1,78 @@
Drone comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub you should configure the Drone container using the following environment variables:
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_GITHUB=true
+ - DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
+ - DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
drone-agent:
image: drone/agent:{{% version %}}
restart: always
depends_on:
- drone-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
```
# Registration
Register your application with GitHub to create your client id and secret. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `<scheme>://<host>/authorize` as the path.
Please use this screenshot for reference:
![github oauth setup](github_oauth.png)
# Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_GITHUB=true
: Set to true to enable the GitHub driver.
DRONE_GITHUB_URL=`https://github.com`
: GitHub server address.
DRONE_GITHUB_CLIENT
: Github oauth2 client id.
DRONE_GITHUB_SECRET
: Github oauth2 client secret.
DRONE_GITHUB_SCOPE=repo,repo:status,user:email,read:org
: Comma-separated Github oauth scope.
DRONE_GITHUB_GIT_USERNAME
: Optional. Use a single machine account username to clone all repositories.
DRONE_GITHUB_GIT_PASSWORD
: Optional. Use a single machine account password to clone all repositories.
DRONE_GITHUB_PRIVATE_MODE=false
: Set to true if Github is running in private mode.
DRONE_GITHUB_MERGE_REF=true
: Set to true to use the `refs/pulls/%d/merge` vs `refs/pulls/%d/head`
DRONE_GITHUB_CONTEXT=continuous-integration/drone
: Customize the GitHub status message context
DRONE_GITHUB_SKIP_VERIFY=false
: Set to true to disable SSL verification.

BIN
docs/administration/github_oauth.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 154 KiB

66
docs/administration/gitlab.md Normal file
View file

@ -0,0 +1,66 @@
Drone comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Drone container using the following environment variables:
```diff
version: '2'
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:8000
- 9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
+ - DRONE_GITLAB=true
+ - DRONE_GITLAB_CLIENT=95c0282573633eb25e82
+ - DRONE_GITLAB_SECRET=30f5064039e6b359e075
+ - DRONE_GITLAB_URL=http://gitlab.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
drone-agent:
image: drone/agent:{{% version %}}
restart: always
depends_on:
- drone-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=drone-server:9000
- DRONE_SECRET=${DRONE_SECRET}
```
# Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_GITLAB=true
: Set to true to enable the GitLab driver.
DRONE_GITLAB_URL=`https://gitlab.com`
: GitLab Server address.
DRONE_GITLAB_CLIENT
: GitLab oauth2 client id.
DRONE_GITLAB_SECRET
: GitLab oauth2 client secret.
DRONE_GITLAB_GIT_USERNAME
: Optional. Use a single machine account username to clone all repositories.
DRONE_GITLAB_GIT_PASSWORD
: Optional. Use a single machine account password to clone all repositories.
DRONE_GITLAB_SKIP_VERIFY=false
: Set to true to disable SSL verification.
DRONE_GITLAB_PRIVATE_MODE=false
: Set to true if GitLab is running in private mode.
# Registration
You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application.
Please use `http://drone.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application.

38
docs/administration/lets_encrypt.md Normal file
View file

@ -0,0 +1,38 @@
Drone supports automated ssl configuration and updates using let's encrypt. You can enable let's encrypt by making the following modifications to your server configuration:
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
+ - 80:80
+ - 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
+ - DRONE_LETS_ENCRYPT=true
```
Note that Drone uses the hostname from the `DRONE_HOST` environment variable when requesting certificates. For example, if `DRONE_HOST=https://foo.com` the certificate is requested for `foo.com`.
>Once enabled you can visit your website at both the http and the https address
# Certificate Cache
Drone writes the certificates to the below directory:
```
/var/lib/drone/golang-autocert
```
# Certificate Updates
Drone uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.

162
docs/administration/prometheus.md Normal file
View file

@ -0,0 +1,162 @@
Drone is compatible with Prometheus and exposes a `/metrics` endpoint. Please note that access to the metrics endpoint is restricted and requires an authorization token with administrative privileges.
```nohighlight
global:
scrape_interval: 60s
scrape_configs:
- job_name: 'drone'
bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
static_configs:
- targets: ['drone.domain.com']
```
# Authorization
An administrator will need to generate a user api token and configure in the prometheus configuration file as a bearer token. Please see the following example:
```diff
global:
scrape_interval: 60s
scrape_configs:
- job_name: 'drone'
+ bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
static_configs:
- targets: ['drone.domain.com']
```
# Metric Reference
List of prometheus metrics specific to Drone:
```
# HELP drone_build_count Total number of builds.
# TYPE drone_build_count gauge
drone_build_count 7275
# HELP drone_pending_jobs Total number of pending build processes.
# TYPE drone_pending_jobs gauge
drone_pending_jobs 0
# HELP drone_repo_count Total number of registered repositories.
# TYPE drone_repo_count gauge
drone_repo_count 133
# HELP drone_running_jobs Total number of running build processes.
# TYPE drone_running_jobs gauge
drone_running_jobs 0
# HELP drone_user_count Total number of active users.
# TYPE drone_user_count gauge
drone_user_count 15
```
List of prometheus metrics for server resource usage:
```
# HELP go_gc_duration_seconds A summary of the GC invocation durations.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0.000189189
go_gc_duration_seconds{quantile="0.25"} 0.000391444
go_gc_duration_seconds{quantile="0.5"} 0.001895967
go_gc_duration_seconds{quantile="0.75"} 0.003075854
go_gc_duration_seconds{quantile="1"} 0.004224575
go_gc_duration_seconds_sum 0.019922696
go_gc_duration_seconds_count 10
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 24
# HELP go_memstats_alloc_bytes Number of bytes allocated and still in use.
# TYPE go_memstats_alloc_bytes gauge
go_memstats_alloc_bytes 2.556344e+06
# HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed.
# TYPE go_memstats_alloc_bytes_total counter
go_memstats_alloc_bytes_total 2.0479656e+07
# HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table.
# TYPE go_memstats_buck_hash_sys_bytes gauge
go_memstats_buck_hash_sys_bytes 1.45144e+06
# HELP go_memstats_frees_total Total number of frees.
# TYPE go_memstats_frees_total counter
go_memstats_frees_total 200332
# HELP go_memstats_gc_cpu_fraction The fraction of this program's available CPU time used by the GC since the program started.
# TYPE go_memstats_gc_cpu_fraction gauge
go_memstats_gc_cpu_fraction 8.821705133777562e-05
# HELP go_memstats_gc_sys_bytes Number of bytes used for garbage collection system metadata.
# TYPE go_memstats_gc_sys_bytes gauge
go_memstats_gc_sys_bytes 557056
# HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and still in use.
# TYPE go_memstats_heap_alloc_bytes gauge
go_memstats_heap_alloc_bytes 2.556344e+06
# HELP go_memstats_heap_idle_bytes Number of heap bytes waiting to be used.
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 3.842048e+06
# HELP go_memstats_heap_inuse_bytes Number of heap bytes that are in use.
# TYPE go_memstats_heap_inuse_bytes gauge
go_memstats_heap_inuse_bytes 4.972544e+06
# HELP go_memstats_heap_objects Number of allocated objects.
# TYPE go_memstats_heap_objects gauge
go_memstats_heap_objects 19986
# HELP go_memstats_heap_released_bytes Number of heap bytes released to OS.
# TYPE go_memstats_heap_released_bytes gauge
go_memstats_heap_released_bytes 0
# HELP go_memstats_heap_sys_bytes Number of heap bytes obtained from system.
# TYPE go_memstats_heap_sys_bytes gauge
go_memstats_heap_sys_bytes 8.814592e+06
# HELP go_memstats_last_gc_time_seconds Number of seconds since 1970 of last garbage collection.
# TYPE go_memstats_last_gc_time_seconds gauge
go_memstats_last_gc_time_seconds 1.4941783810383117e+09
# HELP go_memstats_lookups_total Total number of pointer lookups.
# TYPE go_memstats_lookups_total counter
go_memstats_lookups_total 325
# HELP go_memstats_mallocs_total Total number of mallocs.
# TYPE go_memstats_mallocs_total counter
go_memstats_mallocs_total 220318
# HELP go_memstats_mcache_inuse_bytes Number of bytes in use by mcache structures.
# TYPE go_memstats_mcache_inuse_bytes gauge
go_memstats_mcache_inuse_bytes 2400
# HELP go_memstats_mcache_sys_bytes Number of bytes used for mcache structures obtained from system.
# TYPE go_memstats_mcache_sys_bytes gauge
go_memstats_mcache_sys_bytes 16384
# HELP go_memstats_mspan_inuse_bytes Number of bytes in use by mspan structures.
# TYPE go_memstats_mspan_inuse_bytes gauge
go_memstats_mspan_inuse_bytes 81016
# HELP go_memstats_mspan_sys_bytes Number of bytes used for mspan structures obtained from system.
# TYPE go_memstats_mspan_sys_bytes gauge
go_memstats_mspan_sys_bytes 98304
# HELP go_memstats_next_gc_bytes Number of heap bytes when next garbage collection will take place.
# TYPE go_memstats_next_gc_bytes gauge
go_memstats_next_gc_bytes 4.819216e+06
# HELP go_memstats_other_sys_bytes Number of bytes used for other system allocations.
# TYPE go_memstats_other_sys_bytes gauge
go_memstats_other_sys_bytes 672584
# HELP go_memstats_stack_inuse_bytes Number of bytes in use by the stack allocator.
# TYPE go_memstats_stack_inuse_bytes gauge
go_memstats_stack_inuse_bytes 622592
# HELP go_memstats_stack_sys_bytes Number of bytes obtained from system for stack allocator.
# TYPE go_memstats_stack_sys_bytes gauge
go_memstats_stack_sys_bytes 622592
# HELP go_memstats_sys_bytes Number of bytes obtained from system.
# TYPE go_memstats_sys_bytes gauge
go_memstats_sys_bytes 1.2232952e+07
# HELP go_threads Number of OS threads created
# TYPE go_threads gauge
go_threads 9
# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 0.9
# HELP process_max_fds Maximum number of open file descriptors.
# TYPE process_max_fds gauge
process_max_fds 524288
# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 17
# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes 2.5296896e+07
# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.494177893e+09
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 4.23243776e+08
```

148
docs/administration/proxy.md Normal file
View file

@ -0,0 +1,148 @@
**Table of Contents**
- [Apache](#apache)
- [Nginx](#nginx)
- [Caddy](#caddy)
- [Ngrok](#ngrok)
# Apache
This guide provides a brief overview for installing Drone server behind the Apache2 webserver. This is an example configuration:
```nohighlight
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass / http://127.0.0.1:8000/
ProxyPassReverse / http://127.0.0.1:8000/
```
You must have the below Apache modules installed.
```nohighlight
a2enmod proxy
a2enmod proxy_http
```
You must configure Apache to set `X-Forwarded-Proto` when using https.
```diff
ProxyPreserveHost On
+RequestHeader set X-Forwarded-Proto "https"
ProxyPass / http://127.0.0.1:8000/
ProxyPassReverse / http://127.0.0.1:8000/
```
# Nginx
This guide provides a basic overview for installing Drone server behind the nginx webserver. For more advanced configuration options please consult the official nginx [documentation](https://www.nginx.com/resources/admin-guide/).
Example configuration:
```nginx
server {
listen 80;
server_name drone.example.com;
location / {
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_pass http://127.0.0.1:8000;
proxy_redirect off;
proxy_http_version 1.1;
proxy_buffering off;
chunked_transfer_encoding off;
}
}
```
You must configure the proxy to set `X-Forwarded` proxy headers:
```diff
server {
listen 80;
server_name drone.example.com;
location / {
+ proxy_set_header X-Forwarded-For $remote_addr;
+ proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8000;
proxy_redirect off;
proxy_http_version 1.1;
proxy_buffering off;
chunked_transfer_encoding off;
}
}
```
# Caddy
This guide provides a brief overview for installing Drone server behind the [Caddy webserver](https://caddyserver.com/). This is an example caddyfile proxy configuration:
```nohighlight
drone.mycompany.com {
gzip {
not /stream/
}
proxy / localhost:8000 {
websocket
transparent
}
}
```
You must disable gzip compression for streamed data otherwise the live updates won't be instant:
```diff
drone.mycompany.com {
+ gzip {
+ not /stream/
+ }
proxy / localhost:8000 {
websocket
transparent
}
}
```
You must configure the proxy to enable websocket upgrades:
```diff
drone.mycompany.com {
gzip {
not /stream/
}
proxy / localhost:8000 {
+ websocket
transparent
}
}
```
You must configure the proxy to include `X-Forwarded` headers using the `transparent` directive:
```diff
drone.mycompany.com {
gzip {
not /stream/
}
proxy / localhost:8000 {
websocket
+ transparent
}
}
```
# Ngrok
After installing [ngrok](https://ngrok.com/), open a new console and run:
```
ngrok http 80
```
Set `DRONE_HOST` (for example in `docker-compose.yml`) to the ngrok url (usually xxx.ngrok.io) and start the server.

77
docs/administration/ssl.md Normal file
View file

@ -0,0 +1,77 @@
Drone supports ssl configuration by mounting certificates into your container.
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
+ - 80:80
+ - 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
+ - /etc/certs/drone.foo.com/server.crt:/etc/certs/drone.foo.com/server.crt
+ - /etc/certs/drone.foo.com/server.key:/etc/certs/drone.foo.com/server.key
restart: always
environment:
+ - DRONE_SERVER_CERT=/etc/certs/drone.foo.com/server.crt
+ - DRONE_SERVER_KEY=/etc/certs/drone.foo.com/server.key
```
Update your configuration to expose the following ports:
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
+ - 80:80
+ - 443:443
- 9000:9000
```
Update your configuration to mount your certificate and key:
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:80
- 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
+ - /etc/certs/drone.foo.com/server.crt:/etc/certs/drone.foo.com/server.crt
+ - /etc/certs/drone.foo.com/server.key:/etc/certs/drone.foo.com/server.key
```
Update your configuration to provide the paths of your certificate and key:
```diff
services:
drone-server:
image: drone/drone:{{% version %}}
ports:
- 80:80
- 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
- /etc/certs/drone.foo.com/server.crt:/etc/certs/drone.foo.com/server.crt
- /etc/certs/drone.foo.com/server.key:/etc/certs/drone.foo.com/server.key
restart: always
environment:
+ - DRONE_SERVER_CERT=/etc/certs/drone.foo.com/server.crt
+ - DRONE_SERVER_KEY=/etc/certs/drone.foo.com/server.key
```
# Certificate Chain
The most common problem encountered is providing a certificate file without the intermediate chain.
> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.
# Certificate Errors
SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely. Please do not create issues claiming SSL is broken.

BIN
docs/drone.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

18
docs/motivation.md Normal file
View file

@ -0,0 +1,18 @@
# Motivation
I was using Drone for two years with great satisfaction. The container architecture, the speedy backend and UI, the simple plugin system made it a flexible and simple platform. Kudos for the author, Brad to make it such a joy to use.
It wasn't without flaws
- inconsistencies in variables and CLI features
- lack of documentation
- lack of published best practices
- UI/UX issues
- stuck builds
Things that could be circumvented by reading the codebase. Over time however these started to annoy me, also PRs that tried to address these were not merged. Instead the development of Drone headed towards a 1.0 release with features less interesting to me.
1.0 landed and it came with a licence change. Drone has been an open-core project since many prior versions, but the enterprise features were limited to features like autoscaling and secret vaults.
In the 1.0 line however, Postgresql, Mysql and TLS support along with agent based horizontal scaling were also moved under the enterprise license. Limiting the open source version to single node, hobbyist deployments.
These feature reductions and my long time UX annoyance and general dissatisfaction of the CI space lead to this fork.

49
docs/usage/bash_plugin.md Normal file
View file

@ -0,0 +1,49 @@
This provides a brief tutorial for creating a Drone webhook plugin, using simple shell scripting, to make an http requests during the build pipeline. The below example demonstrates how we might configure a webhook plugin in the Yaml file:
```yaml
pipeline:
webhook:
image: foo/webhook
url: http://foo.com
method: post
body: |
hello world
```
Create a simple shell script that invokes curl using the Yaml configuration parameters, which are passed to the script as environment variables in uppercase and prefixed with `PLUGIN_`.
```bash
#!/bin/sh
curl \
-X ${PLUGIN_METHOD} \
-d ${PLUGIN_BODY} \
${PLUGIN_URL}
```
Create a Dockerfile that adds your shell script to the image, and configures the image to execute your shell script as the main entrypoint.
```dockerfile
FROM alpine
ADD script.sh /bin/
RUN chmod +x /bin/script.sh
RUN apk -Uuv add curl ca-certificates
ENTRYPOINT /bin/script.sh
```
Build and publish your plugin to the Docker registry. Once published your plugin can be shared with the broader Drone community.
```nohighlight
docker build -t foo/webhook .
docker push foo/webhook
```
Execute your plugin locally from the command line to verify it is working:
```nohighlight
docker run --rm \
-e PLUGIN_METHOD=post \
-e PLUGIN_URL=http://foo.com \
-e PLUGIN_BODY="hello world" \
foo/webhook
```

1400
docs/usage/pipeline.md Normal file
View file

File diff suppressed because it is too large Load diff

BIN
docs/usage/repo_list.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 128 KiB