improving installation docs
This commit is contained in:
Brad Rydzewski
parent
5ba7dad0dc
commit
a63f942c1f
19 changed files with 93 additions and 104 deletions
2
docs/build/README.md
vendored
2
docs/build/README.md
vendored
|
|
@ -1,4 +1,4 @@
|
|||
* [Overview](overview.md)
|
||||
* [Overview](index.md)
|
||||
* [Variables](env.md)
|
||||
* [Secrets](secrets.md)
|
||||
* [Cache](cache.md)
|
||||
|
|
|
|||
0
docs/build/overview.md → docs/build/index.md
vendored
0
docs/build/overview.md → docs/build/index.md
vendored
|
|
@ -1,3 +1,3 @@
|
|||
* [Overview](overview.md)
|
||||
* [Overview](index.md)
|
||||
* [Example](example.md)
|
||||
* [Publish](publish.md)
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
* Install
|
||||
* [Ubuntu](ubuntu.md)
|
||||
* [Docker](install.md)
|
||||
* Setup
|
||||
* [Install](index.md)
|
||||
* [Upgrade](upgrade.md)
|
||||
* [Plugins](plugins.md)
|
||||
* Server
|
||||
* [Server](server.md)
|
||||
* [Docker](docker.md)
|
||||
* [Nginx](nginx.md)
|
||||
* Remotes
|
||||
* [GitHub](github.md)
|
||||
* [GitLab](gitlab.md)
|
||||
* [Bitbucket](bitbucket.md)
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
Drone comes with built-in support for Bitbucket. To enable Bitbucket you should configure the Bitbucket driver using the following environment variables:
|
||||
|
||||
```bash
|
||||
REMOTE_DRIVER="bitbucket"
|
||||
REMOTE_CONFIG="https://bitbucket.org?client_id=${client_id}&client_secret=${client_secret}"
|
||||
REMOTE_DRIVER=bitbucket
|
||||
REMOTE_CONFIG=https://bitbucket.org?client_id=${client_id}&client_secret=${client_secret}
|
||||
```
|
||||
|
||||
## Bitbucket configuration
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Docker
|
||||
|
||||
Drone uses the local Docker daemon (at `unix:///var/run/docker.sock`) to execute your builds with 1x concurrency. This section describes how to customize your Docker configuration and concurrency settings using the `DOCKER_*` environment variables.
|
||||
Drone uses the local Docker daemon (at `unix:///var/run/docker.sock`) to execute your builds with 2x concurrency. This section describes how to customize your Docker configuration and concurrency settings using the `DOCKER_*` environment variables.
|
||||
|
||||
Configure a single Docker host (1x build concurrency):
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
Drone comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub you should configure the GitHub driver using the following environment variables:
|
||||
|
||||
```bash
|
||||
REMOTE_DRIVER="github"
|
||||
REMOTE_CONFIG="https://github.com?client_id=${client_id}&client_secret=${client_secret}"
|
||||
REMOTE_DRIVER=github
|
||||
REMOTE_CONFIG=https://github.com?client_id=${client_id}&client_secret=${client_secret}
|
||||
```
|
||||
|
||||
## GitHub configuration
|
||||
|
|
@ -37,4 +37,4 @@ This section lists all connection options used in the connection string format.
|
|||
|
||||
You must register your application with GitHub in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click Register new application.
|
||||
|
||||
Please use `/authorize` as the Authorization callback URL path.
|
||||
Please use `http://drone.mycompany.com/authorize` as the Authorization callback URL.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
Drone comes with built-in support for GitLab version 8.0 and higher. To enable Gitlab you should configure the Gitlab driver using the following environment variables:
|
||||
|
||||
```bash
|
||||
REMOTE_DRIVER="gitlab"
|
||||
REMOTE_CONFIG="https://gitlab.hooli.com?client_id=${client_id}&client_secret=${client_secret}"
|
||||
REMOTE_DRIVER=gitlab
|
||||
REMOTE_CONFIG=https://gitlab.hooli.com?client_id=${client_id}&client_secret=${client_secret}
|
||||
```
|
||||
|
||||
## Gitlab configuration
|
||||
|
|
@ -37,4 +37,4 @@ This section lists all connection options used in the connection string format.
|
|||
|
||||
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 `/authorize` as the Authorization callback URL path.
|
||||
Please use `http://drone.mycompany.com/authorize` as the Authorization callback URL.
|
||||
|
|
|
|||
|
|
@ -37,62 +37,18 @@ Here are some of the Docker options, explained:
|
|||
|
||||
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.
|
||||
|
||||
Once you have your drone container created, then you can start/stop/restart it in below ways.
|
||||
|
||||
## Starting, Stopping, Logs
|
||||
|
||||
Commands to start, stop and restart Drone:
|
||||
|
||||
```
|
||||
docker start drone
|
||||
docker stop drone
|
||||
docker restart drone
|
||||
sudo docker start drone
|
||||
sudo docker stop drone
|
||||
sudo 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
|
||||
|
||||
script
|
||||
/usr/bin/docker start -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
|
||||
sudo docker logs drone
|
||||
```
|
||||
20
docs/setup/nginx.md
Normal file
20
docs/setup/nginx.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# Nginx
|
||||
|
||||
Using a proxy server is **not 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, please ensure you have version 1.3.13 or greater. You also need to configure nginx to write `X-Forwarded_*` headers:
|
||||
|
||||
```
|
||||
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;
|
||||
}
|
||||
```
|
||||
|
||||
Our installation instructions recommend running Drone in a Docker container with port `:80` published. When behind a reverse proxy, you should run the Drone Docker container with `--publish=8000:8000`. This will publish Drone to port `:8000` allowing you to proxy from `:80`.
|
||||
|
|
@ -2,29 +2,20 @@
|
|||
|
||||
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/).
|
||||
For security reasons you must whitelist plugins. The default whitelist includes the official Drone plugins hosted in the [Docker registry](https://registry.hub.docker.com/repos/plugins/). Customize your whitelist by setting the `PLUGIN_FILTER` environment variable. This is a space-separated list and includes glob matching capabilities.
|
||||
|
||||
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
|
||||
Whitelist official Drone plugins
|
||||
|
||||
```
|
||||
PLUGINS=plugins/*
|
||||
PLUGIN_FILTER=plugins/*
|
||||
```
|
||||
|
||||
**Example 2:** whitelist plugins for registry user `octocat`
|
||||
Whitelist official Drone plugins and registry user `octocat`
|
||||
|
||||
```
|
||||
PLUGINS=octocat/*
|
||||
PLUGIN_FILTER=plugins/* octocat/*
|
||||
```
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@
|
|||
Drone comes with support for Postgres as an alternate database engine. To enable Postgres, you should specify the following environment variables:
|
||||
|
||||
```
|
||||
DATABASE_DRIVER="postgres"
|
||||
DATABASE_CONFIG="postgres://root:pa55word@127.0.0.1:5432/postgres"
|
||||
DATABASE_DRIVER=postgres
|
||||
DATABASE_CONFIG=postgres://root:pa55word@127.0.0.1:5432/postgres
|
||||
```
|
||||
|
||||
## Postgres configuration
|
||||
|
|
|
|||
|
|
@ -13,22 +13,22 @@ This section lists all environment variables used to configure the server.
|
|||
This example changes the default port to `:80`:
|
||||
|
||||
```bash
|
||||
SERVER_ADDR=":80"
|
||||
SERVER_ADDR=:80
|
||||
```
|
||||
|
||||
## Server SSL
|
||||
|
||||
Drone uses the `ListenAndServeTLS` function in the Go standard library to accept `https` connections. If you experience any issues configuring `https` please contact us on [gitter](https://gitter.im/drone/drone). Please do not log an issue saying `https` is broken in Drone (it isn't).
|
||||
Drone uses the `ListenAndServeTLS` function in the Go standard library to accept `https` connections. If you experience any issues configuring `https` please contact us on [gitter](https://gitter.im/drone/drone). Please do not log an issue saying `https` is broken in Drone.
|
||||
|
||||
This example accepts `HTTPS` connections:
|
||||
|
||||
```bash
|
||||
SERVER_ADDR=":443"
|
||||
SERVER_KEY="/path/to/key.pem"
|
||||
SERVER_CERT="/path/to/cert.pem"
|
||||
SERVER_ADDR=:443
|
||||
SERVER_KEY=/path/to/key.pem
|
||||
SERVER_CERT=/path/to/cert.pem
|
||||
```
|
||||
|
||||
> **NOTE** if the certificate is signed by a certificate authority, the cert should be the concatenation of the server's certificate followed by the CA's certificate.
|
||||
> When your certificate is signed by an authority, the certificate should be the concatenation of the server's certificate followed by the CA certificate.
|
||||
|
||||
When running Drone inside Docker, you'll need to mount a volume containing the certificate:
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
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:
|
||||
|
||||
```bash
|
||||
DATABASE_DRIVER="sqlite3"
|
||||
DATABASE_CONFIG="/var/lib/drone/drone.sqlite"
|
||||
DATABASE_DRIVER=sqlite3
|
||||
DATABASE_CONFIG=/var/lib/drone/drone.sqlite
|
||||
```
|
||||
|
||||
## Sqlite3 configuration
|
||||
|
|
@ -23,12 +23,4 @@ The components of the datasource connection string are:
|
|||
|
||||
## Sqlite3 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:
|
||||
|
||||
* `vfs` opens the database connection using the VFS value.
|
||||
* `mode` opens the database as `ro`, `rw`, `rwc` or `memory`.
|
||||
* `cache` opens the database with `shared` or `private` cache.
|
||||
* `psow` overrides the powersafe overwrite property of the database file being opened.
|
||||
* `_loc` sets the location of the time format. Use `auto` to auto-detect.
|
||||
* `_busy_timeout` sets the value of the `sqlite3_busy_timeout`
|
||||
* `_txlock` sets the locking behavior to `immediate`, `deferred`, or `exclusive`
|
||||
See the official [driver documentation](https://www.sqlite.org/uri.html#coreqp) for a full list of driver options.
|
||||
|
|
|
|||
28
docs/setup/upgrade.md
Normal file
28
docs/setup/upgrade.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# Upgrading
|
||||
|
||||
Drone is built continuously, with updates available daily. In order to upgrade Drone you must first stop and remove your running Drone instance:
|
||||
|
||||
```
|
||||
sudo docker stop drone
|
||||
sudo docker rm drone
|
||||
```
|
||||
|
||||
Pull the latest Drone image:
|
||||
|
||||
```
|
||||
sudo docker pull drone/drone:0.4
|
||||
```
|
||||
|
||||
Run the container using the latest Drone image:
|
||||
|
||||
```
|
||||
sudo docker run \
|
||||
--volume /var/lib/drone:/var/lib/drone \
|
||||
--volume /var/run/docker.sock:/var/run/docker.sock \
|
||||
--env-file /etc/drone/dronerc \
|
||||
--restart=always \
|
||||
--publish=80:8000 \
|
||||
--detach=true \
|
||||
--name=drone \
|
||||
drone/drone:0.4
|
||||
```
|
||||
|
|
@ -8,19 +8,19 @@ block header
|
|||
li Documentation
|
||||
ul.nav.nav-tabs
|
||||
li.nav-item
|
||||
a[class="nav-link"][href="../setup/ubuntu.html"]
|
||||
a[class="nav-link"][href="../setup/"]
|
||||
.active ? Site.Name == "Install"
|
||||
| Install
|
||||
li.nav-item
|
||||
a[class="nav-link"][href="../build/overview.html"]
|
||||
a[class="nav-link"][href="../build/"]
|
||||
.active ? Site.Name == "Builds"
|
||||
| Builds
|
||||
li.nav-item
|
||||
a[class="nav-link"][href="../plugin/overview.html"]
|
||||
a[class="nav-link"][href="../plugin/"]
|
||||
.active ? Site.Name == "Plugins"
|
||||
| Plugins
|
||||
li.nav-item
|
||||
a.nav-link[href="../api/index.html"] API Reference
|
||||
a.nav-link[href="../api/i"] API Reference
|
||||
|
||||
block content
|
||||
div.container-fluid.docs.docs-usage
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ block content
|
|||
form
|
||||
fieldset.form-group
|
||||
label[for="addr"] Address
|
||||
input.form-control[type="text"][placeholder="unix:///var/run/docker/docker.sock"]#addr
|
||||
input.form-control[type="text"][placeholder="unix:///var/run/docker.sock"]#addr
|
||||
fieldset.form-group
|
||||
label[for="key"] Key
|
||||
textarea.form-control#key
|
||||
|
|
|
|||
|
|
@ -8,11 +8,11 @@ block header
|
|||
li Documentation
|
||||
ul.nav.nav-tabs
|
||||
li.nav-item
|
||||
a.nav-link[href="../setup/ubuntu.html"] Install
|
||||
a.nav-link[href="../setup/"] Install
|
||||
li.nav-item
|
||||
a.nav-link[href="../build/overview.html"] Builds
|
||||
a.nav-link[href="../build/"] Builds
|
||||
li.nav-item
|
||||
a.nav-link[href="../plugin/overview.html"] Plugins
|
||||
a.nav-link[href="../plugin/"] Plugins
|
||||
li.nav-item
|
||||
a.nav-link.active[href="#"] API Reference
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue