diff --git a/doc/build/README.md b/doc/build/README.md new file mode 100644 index 000000000..131815b16 --- /dev/null +++ b/doc/build/README.md @@ -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) diff --git a/doc/build/build.md b/doc/build/build.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/clone.md b/doc/build/clone.md new file mode 100644 index 000000000..00b17e6d9 --- /dev/null +++ b/doc/build/clone.md @@ -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 diff --git a/doc/build/deploy.md b/doc/build/deploy.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/env.md b/doc/build/env.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/matrix.md b/doc/build/matrix.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/notify.md b/doc/build/notify.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/overview.md b/doc/build/overview.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/publish.md b/doc/build/publish.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/selenium.md b/doc/build/selenium.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/build/services.md b/doc/build/services.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/install-docker.md b/doc/install-docker.md index b1630d049..00b655cab 100644 --- a/doc/install-docker.md +++ b/doc/install-docker.md @@ -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. diff --git a/doc/install-ubuntu.md b/doc/install-ubuntu.md deleted file mode 100644 index 9e8fd331b..000000000 --- a/doc/install-ubuntu.md +++ /dev/null @@ -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`. diff --git a/doc/plugins.md b/doc/plugins.md new file mode 100644 index 000000000..8ce81fbd8 --- /dev/null +++ b/doc/plugins.md @@ -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/* +``` diff --git a/doc/setup-bitbucket.md b/doc/setup-bitbucket.md index e6b6e289f..999815c2a 100644 --- a/doc/setup-bitbucket.md +++ b/doc/setup-bitbucket.md @@ -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 -``` \ No newline at end of file +* `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** diff --git a/doc/setup-database.md b/doc/setup-database.md deleted file mode 100644 index 6a64f6a43..000000000 --- a/doc/setup-database.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/doc/setup-docker.md b/doc/setup-docker.md index 4f1476cf2..41efa55cb 100644 --- a/doc/setup-docker.md +++ b/doc/setup-docker.md @@ -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", diff --git a/doc/setup-github.md b/doc/setup-github.md index 403de810b..998b3e1f0 100644 --- a/doc/setup-github.md +++ b/doc/setup-github.md @@ -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. diff --git a/doc/setup-gitlab.md b/doc/setup-gitlab.md index 4576f39b6..3e054c42c 100644 --- a/doc/setup-gitlab.md +++ b/doc/setup-gitlab.md @@ -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 -``` \ No newline at end of file +* `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. diff --git a/doc/setup-nginx.md b/doc/setup-nginx.md deleted file mode 100644 index 1e1a63a64..000000000 --- a/doc/setup-nginx.md +++ /dev/null @@ -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" -``` diff --git a/doc/setup-postgres.md b/doc/setup-postgres.md new file mode 100644 index 000000000..f97320a07 --- /dev/null +++ b/doc/setup-postgres.md @@ -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. diff --git a/doc/setup-sqlite.md b/doc/setup-sqlite.md new file mode 100644 index 000000000..7933c6283 --- /dev/null +++ b/doc/setup-sqlite.md @@ -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" +``` diff --git a/doc/setup.md b/doc/setup.md deleted file mode 100644 index 58dd902a0..000000000 --- a/doc/setup.md +++ /dev/null @@ -1 +0,0 @@ -setup.md \ No newline at end of file