mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-07-02 12:05:56 +00:00
docs / spec for installation and configuration
This commit is contained in:
Brad Rydzewski
parent
f3ea6dbdc5
commit
b0edb8be50
|
|
@ -6,4 +6,5 @@
|
|||
* [Bitbucket](bitbucket.md)
|
||||
* [Database](#)
|
||||
* [SQLite](sqlite.md)
|
||||
* [MySQL](mysql.md)
|
||||
* [Postgres](postgres.md)
|
||||
|
|
|
|||
|
|
@ -1,31 +1,21 @@
|
|||
# Bitbucket
|
||||
|
||||
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:
|
||||
Drone comes with built-in support for Bitbucket. To enable and configure Bitbucket, you should set the following environment variables:
|
||||
|
||||
```
|
||||
bitbucket://host[:port][?options]
|
||||
REMOTE_DRIVER="bitbucket"
|
||||
|
||||
BITBUCKET_KEY="c0aaff74c060ff4a950d"
|
||||
BITBUCKET_SECRET="1ac1eae5ff1b490892f5"
|
||||
BITBUCKET_OPEN="true"
|
||||
BITBUCKET_ORGS="drone,drone-plugins"
|
||||
```
|
||||
|
||||
The components of this string are:
|
||||
## Bitbucket settings
|
||||
|
||||
* `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
|
||||
This section lists all environment variables options used to configure Bitbucket.
|
||||
|
||||
This is an example connection string:
|
||||
|
||||
```bash
|
||||
DRONE_REMOTE="bitbucket://client_key=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
|
||||
```
|
||||
|
||||
## Bitbucket 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:
|
||||
|
||||
* `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**
|
||||
* `BITBUCKET_KEY` oauth client id for registered application
|
||||
* `BITBUCKET_SECRET` oauth client secret for registered application
|
||||
* `BITBUCKET_OPEN=false` allows users to self-register. Defaults to false for security reasons.
|
||||
* `BITBUCKET_ORGS=drone,docker` restricts access to these Bitbucket organizations. **Optional**
|
||||
|
|
|
|||
|
|
@ -1,37 +1,25 @@
|
|||
# GitHub
|
||||
|
||||
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:
|
||||
Drone comes with built-in support for GitHub and GitHub Enterprise. To enable and configure GitHub, you should set the following environment variables:
|
||||
|
||||
```
|
||||
github://host[:port][?options]
|
||||
REMOTE_DRIVER="github"
|
||||
|
||||
GITHUB_CLIENT="c0aaff74c060ff4a950d"
|
||||
GITHUB_SECRET="1ac1eae5ff1b490892f5"
|
||||
```
|
||||
|
||||
The components of this string are:
|
||||
## GitHub settings
|
||||
|
||||
* `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 section lists all environment variables options used to configure GitHub.
|
||||
|
||||
This is an example connection string:
|
||||
|
||||
```bash
|
||||
DRONE_REMOTE="github://github.com?client_id=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
|
||||
```
|
||||
|
||||
## GitHub 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:
|
||||
|
||||
* `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.
|
||||
* `GITHUB_HOST` server address to connect to. The default value is `https://github.com` if not specified.
|
||||
* `GITHUB_CLIENT` oauth client id for registered application
|
||||
* `GITHUB_SECRET` oauth client secret for registered application
|
||||
* `GITHUB_OPEN=false` allows users to self-register. Defaults to false for security reasons.
|
||||
* `GITHUB_ORGS=drone,docker` restricts access to these GitHub organizations. **Optional**
|
||||
* `GITHUB_PRIVATE_MODE=false` indicates GitHub Enterprise is running in private mode
|
||||
|
||||
## GitHub Enterprise
|
||||
|
||||
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.
|
||||
If you are configuring Drone with GitHub Enterprise edition, you must specify the `GITHUB_HOST` in the configuration string. Note that you may also need to set `GITHUB_PRIVATE_MODE=true` when running GitHub Entperirse in private mode.
|
||||
|
|
|
|||
|
|
@ -1,33 +1,25 @@
|
|||
# GitLab
|
||||
|
||||
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:
|
||||
Drone comes with built-in support for GitLab 7.7 and higher. To enable and configure GitLab, you should set the following environment variables:
|
||||
|
||||
```
|
||||
gitlab://host[:port][?options]
|
||||
REMOTE_DRIVER="gitlab"
|
||||
|
||||
GITLAB_HOST="https://gitlab.hooli.com"
|
||||
GITLAB_CLIENT="c0aaff74c060ff4a950d"
|
||||
GITLAB_SECRET="1ac1eae5ff1b490892f5"
|
||||
GITLAB_OPEN="true"
|
||||
GITLAB_ORGS="drone,drone-plugins"
|
||||
GITLAB_SKIP_VERIFY="false"
|
||||
```
|
||||
|
||||
The components of this string are:
|
||||
## GitLab settings
|
||||
|
||||
* `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
|
||||
This section lists all environment variables options used to configure GitLab.
|
||||
|
||||
This is an example connection string:
|
||||
|
||||
```bash
|
||||
DRONE_REMOTE="gitlab://gitlab.hooli.com?client_id=c0aaff74c060ff4a950d&client_secret=1ac1eae5ff1b490892f5546f837f306265032412"
|
||||
```
|
||||
|
||||
## GitLab 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:
|
||||
|
||||
* `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.
|
||||
* `GITLAB_HOST` server address to connect to.
|
||||
* `GITLAB_CLIENT` oauth client id for registered application
|
||||
* `GITLAB_SECRET` oauth client secret for registered application
|
||||
* `GITLAB_OPEN=false` allows users to self-register. Defaults to false for security reasons.
|
||||
* `GITLAB_ORGS=drone,docker` restricts access to these GitLab organizations. **Optional**
|
||||
* `GITLAB_SKIP_VERIFY=false` skip certificate chain and host name. Defaults to false for security reasons.
|
||||
|
|
|
|||
|
|
@ -1,20 +1,20 @@
|
|||
# Installation
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```bash
|
||||
```
|
||||
sudo docker run \
|
||||
--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" \
|
||||
--env-file /etc/defaults/drone \
|
||||
--restart=always \
|
||||
--publish=80:8000 \
|
||||
--detach=true \
|
||||
--name=drone \
|
||||
drone/drone:latest
|
||||
drone/drone
|
||||
```
|
||||
|
||||
Drone is now running (in the background) on `http://localhost:80`
|
||||
Drone is now running (in the background) on `http://localhost:80`. Note that before running you should create the `--env-file` and add your Drone configuration (GitHub, Bitbucket, GitLab credentials, etc).
|
||||
|
||||
## Docker options
|
||||
|
||||
|
|
@ -25,11 +25,70 @@ Here are some of the Docker options, explained:
|
|||
* `--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
|
||||
* `--env-file /etc/defaults/drone` loads an external file with environment variables. Used to configure Drone.
|
||||
|
||||
## Drone settings
|
||||
|
||||
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.
|
||||
Drone uses environment variables for runtime settings and configuration, such as GitHub, GitLab, plugins and more. These settings can be provided to Docker using an `--env-file` as seen above.
|
||||
|
||||
## Standalone Install
|
||||
## Starting, Stopping, Logs
|
||||
|
||||
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.
|
||||
Commands to start, stop and restart Drone:
|
||||
|
||||
```
|
||||
docker start drone
|
||||
docker stop drone
|
||||
docker restart drone
|
||||
```
|
||||
|
||||
And to view the Drone logs:
|
||||
|
||||
```
|
||||
docker logs drone
|
||||
```
|
||||
|
||||
## Upstart
|
||||
|
||||
Drone can be configured to work with process managers, such as **Ubuntu** Upstart, to automatically start when the operating system initializes. Here is an example upstart script that can be placed in `/etc/init/drone.conf`:
|
||||
|
||||
```
|
||||
description "Drone container"
|
||||
|
||||
start on filesystem and started docker
|
||||
stop on runlevel [!2345]
|
||||
respawn
|
||||
|
||||
pre-start script
|
||||
/usr/bin/docker rm -f drone
|
||||
end script
|
||||
|
||||
script
|
||||
/usr/bin/docker run -a drone
|
||||
end script
|
||||
```
|
||||
|
||||
Commands to start and stop Drone:
|
||||
|
||||
```
|
||||
sudo start drone
|
||||
sudo stop drone
|
||||
```
|
||||
|
||||
## Systemd
|
||||
|
||||
Drone can be configured to work with Systemd to automatically start when the operating system initializes. Here is an example systemd file:
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=Drone container
|
||||
Requires=docker.service
|
||||
After=docker.service
|
||||
|
||||
[Service]
|
||||
Restart=always
|
||||
ExecStart=/usr/bin/docker start -a drone
|
||||
ExecStop=/usr/bin/docker stop -t 2 drone
|
||||
|
||||
[Install]
|
||||
WantedBy=local.target
|
||||
```
|
||||
|
|
|
|||
37
doc/setup/mysql.md
Normal file
37
doc/setup/mysql.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
> **NOTE** the mysql driver is disable until driver issue [#257](https://github.com/go-sql-driver/mysql/issues/257) is resolved
|
||||
|
||||
# MySQL
|
||||
|
||||
Drone comes with support for MySQL as an alternate database engine. To enable Postgres, you should specify the following environment variables:
|
||||
|
||||
```
|
||||
DATASTORE_DRIVER="mysql"
|
||||
DATASTORE_CONFIG="root:pa55word@tcp(localhost:3306)/drone"
|
||||
```
|
||||
|
||||
## MySQL connection
|
||||
|
||||
The following is the standard URI connection scheme:
|
||||
|
||||
```
|
||||
[username[:password]@][protocol[(address)]]/dbname[?options]
|
||||
```
|
||||
|
||||
The components of this string are:
|
||||
|
||||
* `username` optional. Use this username when connecting to the MySQL instance.
|
||||
* `password` optional. Use this password when connecting to the MySQL instance.
|
||||
* `protocol` server protocol to connect with.
|
||||
* `address` server address to connect to.
|
||||
* `dbname` name of the database to connect to
|
||||
* `?options` connection specific options
|
||||
|
||||
This is an example connection string:
|
||||
|
||||
```
|
||||
root:pa55word@tcp(localhost:3306)/drone?autocommit=false
|
||||
```
|
||||
|
||||
## MySQL options
|
||||
|
||||
See the official [driver documentation](https://github.com/go-sql-driver/mysql#parameters) for a full list of driver options.
|
||||
|
|
@ -1,7 +1,14 @@
|
|||
|
||||
# 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.
|
||||
Drone comes with support for Postgres as an alternate database engine. To enable Postgres, you should specify the following environment variables:
|
||||
|
||||
```
|
||||
DATASTORE_DRIVER="postgres"
|
||||
DATASTORE_CONFIG="postgres://root:pa55word@127.0.0.1:5432/postgres"
|
||||
```
|
||||
|
||||
## Postgres connection
|
||||
|
||||
The following is the standard URI connection scheme:
|
||||
|
||||
|
|
@ -11,7 +18,7 @@ postgres://[username:password@]host[:port]/[dbname][?options]
|
|||
|
||||
The components of this string are:
|
||||
|
||||
* `postgres://` required prefix to load the Postgres driver
|
||||
* `postgres://` required prefix
|
||||
* `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.
|
||||
|
|
@ -20,8 +27,8 @@ The components of this string are:
|
|||
|
||||
This is an example connection string:
|
||||
|
||||
```bash
|
||||
DRONE_DATASTORE="postgres://root:pa55word@127.0.0.1:5432/postgres"
|
||||
```
|
||||
postgres://root:pa55word@127.0.0.1:5432/postgres
|
||||
```
|
||||
|
||||
## Postgres options
|
||||
|
|
|
|||
|
|
@ -1,20 +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:
|
||||
Drone uses SQLite as the default database with zero configuration required. In order to customize the SQLite database configuration you should specify the following environment variables:
|
||||
|
||||
```
|
||||
sqlite3://path
|
||||
DATASTORE_DRIVER="sqlite3"
|
||||
DATASTORE_CONFIG="/var/lib/drone/drone.sqlite"
|
||||
```
|
||||
|
||||
The components of this string are:
|
||||
## Sqlite3 connection
|
||||
|
||||
* `sqlite3://` required prefix to load the sqlite3 driver
|
||||
* `host` local path to sqlite database. The default value is `/var/lib/drone/drone.sqlite`.
|
||||
The components of this connection string are:
|
||||
|
||||
* `path` 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"
|
||||
```
|
||||
/var/lib/drone/drone.sqlite
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue