mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-07-02 12:05:56 +00:00
Code Issues Projects Releases Wiki Activity

continued work on docs

Browse source
This commit is contained in:
Brad Rydzewski 2015-07-06 21:13:50 -07:00
parent 342e78a16b
commit 817eab7cae
23 changed files with 261 additions and 235 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc/build/README.md vendored Normal file
View file

@ -0,0 +1,10 @@
* [Overview](overview.md)
* [Environment](env.md)
* [Clone](clone.md)
* [Build](build.md)
* [Matrix](martrix.md)
* [Publish](publish.md)
* [Deploy](deploy.md)
* [Notify](notify.md)
* [Services](services.md)
* [Selenium](selenium.md)

0
doc/build/build.md vendored Normal file
View file

53
doc/build/clone.md vendored Normal file
View file

@ -0,0 +1,53 @@
# Clone
Drone automatically clones your repository and submodules at the start of your build. No configuration is required, however, you can use the `clone` section of the `.drone.yml` to customize this behavior.
## Clone Options
The custom clone options are:
* `depth` creates a shallow clone with truncated history
* `recursive` recursively clones git submodules
* `path` relative path inside `/drone/src` where the repository is cloned
This is an example yaml configuration:
```
clone:
depth: 50
recursive: true
path: github.com/drone/drone
```
resulting in the following clone command:
```
git clone --depth=50 --recusive=true \
https://github.com/drone/drone.git \
/drone/src/github.com/drone/drone
```
## Authentication
Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` files to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
Drone prefers using `netrc` files for authentication because they allow you to clone other private repositories. This is helpful when you have third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
Drone only injects the `.netrc` file and `ssh` keys into your build environment if your repository is private, or if the remote system is running in private mode. We do this for security reasons to avoid leaking sensitive data.
## Custom Plugin
You can override the default `git` plugin by specifying an alternative plugin image. An example use case may be integrating with alternate version control systems, such as mercurial:
```yml
clone:
image: bradrydzewski/hg
# below are plubin-specific parameters
path: override/default/clone/path
insecure: false
verbose: true
```
Please reference the official `git` plugin and use this as a starting point for custom plugin development:
https://github.com/drone-plugins/drone-git

0
doc/build/deploy.md vendored Normal file
View file

0
doc/build/env.md vendored Normal file
View file

0
doc/build/matrix.md vendored Normal file
View file

0
doc/build/notify.md vendored Normal file
View file

0
doc/build/overview.md vendored Normal file
View file

0
doc/build/publish.md vendored Normal file
View file

0
doc/build/selenium.md vendored Normal file
View file

0
doc/build/services.md vendored Normal file
View file

57
doc/install-docker.md
View file

@ -1,44 +1,35 @@
An official Drone image is available in the [Docker registry](https://registry.hub.docker.com/u/drone/drone/). This is the recommended way to install and run Drone on non-Ubuntu environments. Pull the latest Drone image to get started:
# Installation
```bash
sudo docker pull drone/drone
```
An example command to run your Drone instance with GitHub enabled:
```bash
sudo docker run -d \
-v /var/lib/drone:/var/lib/drone \
-e DRONE_GITHUB_CLIENT=c0aaff74c060ff4a950d \
-e DRONE_GITHUB_SECRET=1ac1eae5ff1b490892f5 \
-p 80:80 --name=drone drone/drone
```
### Persistence
When running Drone inside Docker we recommend mounting a volume for your sqlite database. This ensures the database is not lost if the container is accidentally stopped and removed. Below is an example that mounts `/var/lib/drone` on your host machine:
To quickly tryout Drone we have a [Docker image](https://registry.hub.docker.com/u/drone/drone/) that includes everything you need to get started. Simply run the commend below, substituted with your GitHub credentials:
```bash
sudo docker run \
-v /var/lib/drone:/var/lib/drone \
--name=drone drone/drone
--volume /var/lib/drone:/var/lib/drone \
--volume /var/run/docker.sock:/var/run/docker.sock \
--env DRONE_REMOTE="github://client_id=1ac1eae5ff1b490892f5&client_secret=c0aaff74c060ff4a950d" \
--restart=always \
--publish=80:8000 \
--detach=true \
--name=drone \
drone/drone:latest
```
### Configuration
Drone is now running (in the background) on `http://localhost:80`
When running Drone inside Docker we recommend using environment variables to configure the system. All configuration attributes in the `drone.toml` may also be provided as environment variables. Below demonstrates how to configure GitHub from environment variables:
## Docker options
```bash
sudo docker run \
-e DRONE_GITHUB_CLIENT=c0aaff74c060ff4a950d \
-e DRONE_GITHUB_SECRET=1ac1eae5ff1b490892f5 \
--name=drone drone/drone
```
Here are some of the Docker options, explained:
### Logging
* `--restart=always` starts Drone automatically during system init process
* `--publish=80:8000` runs Drone on port `80`
* `--detach=true` starts Drone in the background
* `--volume /var/lib/drone:/var/lib/drone` mounted volume to persist sqlite database
* `--volume /var/run/docker.sock:/var/run/docker.sock` mounted volume to access Docker and spawn builds
When running Drone inside Docker the logs are sent to stdout / stderr. You can view the log output by running the following command:
## Drone settings
```bash
docker logs drone
```
Drone uses environment variables for runtime settings and configuration, such as GitHub, GitLab, plugins and more. These settings can be provided to Docker using `--env` command as seen above.
## Standalone Install
Running Drone inside Docker is recommended but by no means required. Drone compiles to a single binary file with zero dependencies. To simplify support, however, we no longer ship a binary distribution and encourage everyone to run Drone inside Docker.

39
doc/install-ubuntu.md
View file

@ -1,39 +0,0 @@
These are the instructions for running Drone on Ubuntu . We recommend using Ubuntu 14.04, the latest stable distribution. We also highly recommend using AUFS as the default file system driver for Docker.
### System Requirements
The default Drone installation uses a SQLite3 database for persistence. Please ensure you have `libsqlite3-dev` installed:
```bash
sudo apt-get update
sudo apt-get install libsqlite3-dev
```
The default Drone installation also assumes Docker is installed locally on the host machine. To install Docker on Ubuntu:
```bash
wget -qO- https://get.docker.com/ | sh
```
### Installation
Once the environment is prepared you can install Drone from a debian file. Drone will automatically start on port 80. Edit /etc/drone/drone.toml to modify the port.
```bash
wget downloads.drone.io/0.4.0/drone.deb
sudo dpkg --install drone.deb
```
### Start & Stop
The Drone service is managed by upstart and can be started, stopped or restarted using the following commands:
```bash
sudo start drone
sudo stop drone
sudo restart drone
```
### Logging
The Drone service logs are written to `/var/log/upstart/drone.log`.

30
doc/plugins.md Normal file
View file

@ -0,0 +1,30 @@
# Plugins
Plugins are Docker containers, executed during your build process. Plugins are downloaded automatically, on-demand as they are encountered in your `.drone.yml` file.
Plugin examples include:
* `git` plugin to clone your repository
* `gh_pages` plugin to publish documentation to GitHub pages
* `slack` plugin to notify your Slack channel when a build completes
* `s3` plugin to push files or build artifacts to your S3 bucket
See the [plugin marketplace](http://addons.drone.io) for a full catalog of official plugins.
## Security
For security reasons you must whitelist plugins. The default whitelist matches the official Drone plugins -- `plugins/drone` hosted in the [Docker registry](https://registry.hub.docker.com/repos/plugins/).
You can customize your whitelist by setting the `PLUGINS` environment variable. Note that you can use globbing to whitelist all Docker images with a defined prefix:
**Example 1:** whitelist official Drone plugins
```
PLUGINS=plugins/*
```
**Example 2:** whitelist plugins for registry user `octocat`
```
PLUGINS=octocat/*
```

37
doc/setup-bitbucket.md
View file

@ -1,28 +1,31 @@
You may configure Drone to integrate with Bitbucket. This can be configured in the `/etc/drone/drone.toml` configuration file:
# Bitbucket
```ini
[bitbucket]
client = "c0aaff74c060ff4a950d"
secret = "1ac1eae5ff1b490892f5546f837f306265032412"
open = false
Drone comes with built-in support for Bitbucket. To enable Bitbucket, you must specify the `DRONE_REMOTE` environment variable with the URI configuration string. This section describes the URI format for configuring the Bitbucket driver.
The following is the standard URI connection scheme:
```
bitbucket://host[:port][?options]
```
Please note this has security implications. This setting should only be enabled if you are running Drone behind a firewall.
The components of this string are:
### Environment Variables
* `bitbucket://` required prefix to load the Bitbucket driver
* `host` server address to connect to
* `:port` optional. The default value is `:80` if not specified.
* `?options` connection specific options
You may also configure Bitbucket using environment variables. This is useful when running Drone inside Docker containers, for example.
This is an example connection string:
```bash
DRONE_BITBUCKET_CLIENT="c0aaff74c060ff4a950d"
DRONE_BITBUCKET_SECRET="1ac1eae5ff1b490892f5546f837f306265032412"
DRONE_REMOTE="bitbucket://client_key=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
```
### User Registration
## Bitbucket options
User registration is closed by default and new accounts must be provisioned in the user interface. You may allow users to self-register with the following configuration flag:
This section lists all connection options used in the connection string format. Connection options are pairs in the following form: `name=value`. The value is always case sensitive. Separate options with the ampersand (i.e. &) character:
```ini
[bitbucket]
open = true
```
* `client_key` oauth client key for registered application
* `client_secret` oauth client secret for registered application
* `open=false` allows users to self-register. Defaults to false for security reasons.
* `orgs=drone,docker` restricts access to these Bitbucket organizations. **Optional**

35
doc/setup-database.md
View file

@ -1,35 +0,0 @@
SQLite is the default database driver. Drone will automatically create a database file at `/var/lib/drone/drone.sqlite` and will handle database schema setup and migration. You can further customize the database driver and configuration in the `drone.toml` file:
```ini
[database]
driver = "sqlite3"
datasource = "/var/lib/drone/drone.sqlite"
```
You may also configure the database using environment variables:
```bash
DRONE_DATABASE_DRIVER="sqlite3"
DRONE_DATABASE_DATASOURCE="/var/lib/drone/drone.sqlite"
```
### Postgres
You may alternatively configure Drone to use a Postgres database:
```ini
[database]
driver = "postgres"
datasource = "host=127.0.0.1 user=postgres dbname=drone sslmode=disable"
```
For more details about how to configure the datasource string please see the official driver documentation:
http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
### MySQL
Drone does not include support for MySQL at this time. We hope to include support for MySQL in the future, once the following issue is resolved:
https://github.com/go-sql-driver/mysql/issues/257

32
doc/setup-docker.md
View file

@ -3,20 +3,32 @@ Drone is configured to connect to the local Docker daemon. Drone will attempt to
You can modify the Docker daemon URL in the Drone configuration file:
```ini
[docker]
nodes=[
[docker]
nodes=[
"unix:///var/run/docker.sock",
"unix:///var/run/docker.sock"
]
```
```
DOCKER_HOST="unix:///var/run/docker.sock"
DOCKER_HOST_1="unix:///var/run/docker.sock"
DOCKER_HOST_2="unix:///var/run/docker.sock"
DOCKER_HOST_3="unix:///var/run/docker.sock"
DOCKER_CA
DOCKER_CERT
DOCKER_KEY
DOCKER_HOST
DOCKER_HOST_*
```
### Concurrency
Each node is capable of processing a single build. Therefore, the below configuration will only execute one build at a time:
```ini
[docker]
nodes=[
[docker]
nodes=[
"unix:///var/run/docker.sock"
]
```
@ -24,8 +36,8 @@ nodes=[
In order to increase concurrency you can increase the number of nodes. The below configuration is capable of processing four builds at a time, all using the local Docker daemon:
```ini
[docker]
nodes=[
[docker]
nodes=[
"unix:///var/run/docker.sock",
"unix:///var/run/docker.sock",
"unix:///var/run/docker.sock",
@ -43,16 +55,16 @@ https://gist.github.com/bradrydzewski/a6090115b3fecfc25280
This will generate the following files:
* ca.pem
* cert.pem
* key.pem
* server-cert.pem
* cert.pem
* key.pem
* server-cert.pem
* server-key.pem
Update your Drone configuration to use the `cert.pem` and `key.pem` files and remote daemon URLs:
```ini
[docker]
cert="/path/to/cert.pem"
cert="/path/to/cert.pem"
key="/path/to/key.pem"
nodes = [
"tcp://172.17.42.1:2376",

62
doc/setup-github.md
View file

@ -1,49 +1,37 @@
You may configure Drone to integrate with GitHub or GitHub enterprise. This can be configured in the `/etc/drone/drone.toml` configuration file:
# GitHub
```ini
[github]
client = "c0aaff74c060ff4a950d"
secret = "1ac1eae5ff1b490892f5546f837f306265032412"
Drone comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub, you must specify the `DRONE_REMOTE` environment variable with the URI configuration string. This section describes the URI format for configuring the github driver.
The following is the standard URI connection scheme:
```
github://host[:port][?options]
```
### Environment Variables
The components of this string are:
You may also configure GitHub using environment variables. This is useful when running Drone inside Docker containers, for example.
* `github://` required prefix to load the github driver
* `host` server address to connect to. The default value is `github.com` if not specified.
* `:port` optional. The default value is `:80` if not specified.
* `?options` connection specific options
This is an example connection string:
```bash
DRONE_GITHUB_CLIENT="c0aaff74c060ff4a950d"
DRONE_GITHUB_SECRET="1ac1eae5ff1b490892f5546f837f306265032412"
DRONE_REMOTE="github://github.com?client_id=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
```
### Github Enterprise
## GitHub options
You may also configure Drone to integrate with GitHub Enterprise. Note that if you are running GitHub Enterprise in private mode you should set `private_mode=true`, forcing Drone to clone public repositories with git+ssh.
This section lists all connection options used in the connection string format. Connection options are pairs in the following form: `name=value`. The value is always case sensitive. Separate options with the ampersand (i.e. &) character:
```ini
[github_enterprise]
url = "https://github.drone.io"
api = "https://github.drone.io/api/v3/"
client = "c0aaff74c060ff4a950d"
secret = "1ac1eae5ff1b490892f5546f837f306265032412"
private_mode = false
```
* `client_id` oauth client id for registered application
* `client_secret` oauth client secret for registered application
* `open=false` allows users to self-register. Defaults to false for security reasons.
* `orgs=drone,docker` restricts access to these GitHub organizations. **Optional**
* `private_mode=false` indicates GitHub Enterprise is running in private mode
* `ssl=true` initiates the connection with TLS/SSL. Defaults to true.
### User Registration
## GitHub Enterprise
User registration is closed by default and new accounts must be provisioned in the user interface. You may allow users to self-register with the following configuration flag:
```ini
[github]
open = true
```
Please note this has security implications. This setting should only be enabled if you are running Drone behind a firewall.
### Organization Whitelists
When specified, only users belonging to these organization may login to the system. Use this option to enable self-registration while still limiting access to the general public.
```ini
[github]
orgs = [ "drone", "docker" ]
```
If you are configuring Drone with GitHub Enterprise edition, you must specify the `host` in the configuration string. Note that you may also need to set `private_mode=true` when running GitHub Entperirse in private mode.

62
doc/setup-gitlab.md
View file

@ -1,51 +1,33 @@
You may configure Drone to integrate with GitLab (version 7.9 or higher). This can be configured in the `/etc/drone/drone.toml` configuration file:
# GitLab
```ini
[gitlab]
url = "https://gitlab.com"
client = "c0aaff74c060ff4a950d"
secret = "1ac1eae5ff1b490892f5546f837f306265032412"
skip_verify=false
open=false
Drone comes with built-in support for GitLab version 7.7 and higher. To enable GitLab, you must specify the `DRONE_REMOTE` environment variable with the URI configuration string. This section describes the URI format for configuring the GitLab driver.
The following is the standard URI connection scheme:
```
gitlab://host[:port][?options]
```
Or a custom installation:
The components of this string are:
```ini
[gitlab]
url = "http://gitlab.drone.io"
client = "c0aaff74c060ff4a950d"
secret = "1ac1eae5ff1b490892f5546f837f306265032412"
skip_verify=false
open=false
```
* `gitlab://` required prefix to load the GitLab driver
* `host` server address to connect to.
* `:port` optional. The default value is `:80` if not specified.
* `?options` connection specific options
### Environment Variables
You may also configure Gitlab using environment variables. This is useful when running Drone inside Docker containers, for example.
This is an example connection string:
```bash
DRONE_GITLAB_URL="https://gitlab.com"
DRONE_GITLAB_CLIENT="c0aaff74c060ff4a950d"
DRONE_GITLAB_SECRET="1ac1eae5ff1b490892f5546f837f306265032412"
DRONE_REMOTE="gitlab://gitlab.hooli.com?client_id=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
```
### User Registration
## GitLab options
User registration is closed by default and new accounts must be provisioned in the user interface. You may allow users to self-register with the following configuration flag:
This section lists all connection options used in the connection string format. Connection options are pairs in the following form: `name=value`. The value is always case sensitive. Separate options with the ampersand (i.e. &) character:
```ini
[gitlab]
open = true
```
Please note this has security implications. This setting should only be enabled if you are running Drone behind a firewall.
### Self-Signed Certs
If your Gitlab installation uses a self-signed certificate you may need to instruct Drone to skip TLS verification. This is not recommended, but if you have no other choice you can include the following:
```ini
[gitlab]
skip_verify=true
```
* `client_id` oauth client id for registered application
* `client_secret` oauth client secret for registered application
* `open=false` allows users to self-register. Defaults to false for security reasons.
* `orgs=drone,docker` restricts access to these GitLab organizations. **Optional**
* `skip_verify=false` skip ca verification if self-signed certificate. Defaults to false for security reasons.
* `ssl=true` initiates the connection with TLS/SSL. Defaults to true.

23
doc/setup-nginx.md
View file

@ -1,23 +0,0 @@
Using a proxy server is not really necessary. Drone serves most static content from a CDN and uses the Go standard library’s high-performance net/http package to serve dynamic content. If using Nginx to proxy traffic to Drone you may use the following configuration:
```nginx
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header Origin "";
proxy_pass http://127.0.0.1:8000;
proxy_redirect off;
}
```
It is very important to set the `X-Forwarded-For` and `X-Forwarded-Proto` header variables. Drone needs to know its own URL so that it can configure a repository's post-commit hooks properly.
You may also want to change Drone’s default port when proxying traffic. You can change the port in the `/etc/drone/drone.toml` configuration file:
```toml
[server]
addr = ":8000"
```

35
doc/setup-postgres.md Normal file
View file

@ -0,0 +1,35 @@
# Postgres
Drone comes with support for Postgres as an alternate database engine. To enable Postgres, you must specify the `DRONE_DATASTORE` environment variable with the URI configuration string. This section describes the URI format for configuring the Postgres driver.
The following is the standard URI connection scheme:
```
postgres://[username:password@]host[:port]/[dbname][?options]
```
The components of this string are:
* `postgres://` required prefix to load the Postgres driver
* `username:password@` optional. Use these credentials when connecting to the Postgres instance.
* `host` server address to connect to. It may be a hostname, IP address, or UNIX domain socket.
* `:port` optional. The default value is `:5432` if not specified.
* `dbname` name of the database to connect to
* `?options` connection specific options
This is an example connection string:
```bash
DRONE_DATASTORE="postgres://root:pa55word@127.0.0.1:5432/postgres"
```
## Postgres options
This section lists all connection options used in the connection string format. Connection options are pairs in the following form: `name=value`. The value is always case sensitive. Separate options with the ampersand (i.e. &) character:
* `sslmode` initiates the connection with TLS/SSL (disable, require, verify-ca, verify-full)
* `connect_timeout` maximum wait for connection, in seconds.
* `sslcert` cert file location. The file must contain PEM encoded data.
* `sslkey` key file location. The file must contain PEM encoded data.
* `sslrootcert` location of the root certificate file. The file must contain PEM encoded data.

20
doc/setup-sqlite.md Normal file
View file

@ -0,0 +1,20 @@
# SQLite
Drone uses SQLite as the default database. It requires zero configuration or installation, and can easily scale to meet the needs of most teams. If you need to customize SQLite, you must specify the `DRONE_DATASTORE` environment variable with the URI configuration string. This section describes the URI format for configuring the sqlite3 driver.
The following is the standard URI connection scheme:
```
sqlite3://path
```
The components of this string are:
* `sqlite3://` required prefix to load the sqlite3 driver
* `host` local path to sqlite database. The default value is `/var/lib/drone/drone.sqlite`.
This is an example connection string:
```bash
DRONE_DATASTORE="sqlite3:///var/lib/drone/drone.sqlite"
```

1
doc/setup.md
View file

@ -1 +0,0 @@
setup.md