From a63f942c1f468c54f74ab1605acf215b7b787c62 Mon Sep 17 00:00:00 2001 From: Brad Rydzewski Date: Wed, 7 Oct 2015 17:17:15 -0700 Subject: [PATCH] improving installation docs --- docs/build/README.md | 2 +- docs/build/{overview.md => index.md} | 0 docs/plugin/README.md | 2 +- docs/plugin/{overview.md => index.md} | 0 docs/setup/README.md | 10 +++--- docs/setup/bitbucket.md | 4 +-- docs/setup/docker.md | 2 +- docs/setup/github.md | 6 ++-- docs/setup/gitlab.md | 6 ++-- docs/setup/{install.md => index.md} | 52 +++------------------------ docs/setup/nginx.md | 20 +++++++++++ docs/setup/plugins.md | 19 +++------- docs/setup/postgres.md | 4 +-- docs/setup/server.md | 12 +++---- docs/setup/sqlite.md | 14 ++------ docs/setup/upgrade.md | 28 +++++++++++++++ template/amber/docs.amber | 8 ++--- template/amber/nodes.amber | 2 +- template/amber/swagger.amber | 6 ++-- 19 files changed, 93 insertions(+), 104 deletions(-) rename docs/build/{overview.md => index.md} (100%) rename docs/plugin/{overview.md => index.md} (100%) rename docs/setup/{install.md => index.md} (60%) create mode 100644 docs/setup/nginx.md create mode 100644 docs/setup/upgrade.md diff --git a/docs/build/README.md b/docs/build/README.md index 792e86a6..1175a4c2 100644 --- a/docs/build/README.md +++ b/docs/build/README.md @@ -1,4 +1,4 @@ -* [Overview](overview.md) +* [Overview](index.md) * [Variables](env.md) * [Secrets](secrets.md) * [Cache](cache.md) diff --git a/docs/build/overview.md b/docs/build/index.md similarity index 100% rename from docs/build/overview.md rename to docs/build/index.md diff --git a/docs/plugin/README.md b/docs/plugin/README.md index 6cd566a1..5122322f 100644 --- a/docs/plugin/README.md +++ b/docs/plugin/README.md @@ -1,3 +1,3 @@ -* [Overview](overview.md) +* [Overview](index.md) * [Example](example.md) * [Publish](publish.md) diff --git a/docs/plugin/overview.md b/docs/plugin/index.md similarity index 100% rename from docs/plugin/overview.md rename to docs/plugin/index.md diff --git a/docs/setup/README.md b/docs/setup/README.md index d8366e40..30da995a 100644 --- a/docs/setup/README.md +++ b/docs/setup/README.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) diff --git a/docs/setup/bitbucket.md b/docs/setup/bitbucket.md index a205d994..0a4bffa8 100644 --- a/docs/setup/bitbucket.md +++ b/docs/setup/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 diff --git a/docs/setup/docker.md b/docs/setup/docker.md index f5cb31a3..480ebbb2 100644 --- a/docs/setup/docker.md +++ b/docs/setup/docker.md @@ -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): diff --git a/docs/setup/github.md b/docs/setup/github.md index 3e5b0e5e..058eed37 100644 --- a/docs/setup/github.md +++ b/docs/setup/github.md @@ -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. diff --git a/docs/setup/gitlab.md b/docs/setup/gitlab.md index 8250db97..6166074c 100644 --- a/docs/setup/gitlab.md +++ b/docs/setup/gitlab.md @@ -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. diff --git a/docs/setup/install.md b/docs/setup/index.md similarity index 60% rename from docs/setup/install.md rename to docs/setup/index.md index 931c1d5f..2fd02312 100644 --- a/docs/setup/install.md +++ b/docs/setup/index.md @@ -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 ``` diff --git a/docs/setup/nginx.md b/docs/setup/nginx.md new file mode 100644 index 00000000..02ae4c74 --- /dev/null +++ b/docs/setup/nginx.md @@ -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`. diff --git a/docs/setup/plugins.md b/docs/setup/plugins.md index 8ce81fbd..0a8d9e49 100644 --- a/docs/setup/plugins.md +++ b/docs/setup/plugins.md @@ -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/* ``` diff --git a/docs/setup/postgres.md b/docs/setup/postgres.md index 864cec0b..39ac6a57 100644 --- a/docs/setup/postgres.md +++ b/docs/setup/postgres.md @@ -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 diff --git a/docs/setup/server.md b/docs/setup/server.md index d685271c..bc1614ba 100644 --- a/docs/setup/server.md +++ b/docs/setup/server.md @@ -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: diff --git a/docs/setup/sqlite.md b/docs/setup/sqlite.md index f275f71a..0d0f2548 100644 --- a/docs/setup/sqlite.md +++ b/docs/setup/sqlite.md @@ -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. diff --git a/docs/setup/upgrade.md b/docs/setup/upgrade.md new file mode 100644 index 00000000..1548e472 --- /dev/null +++ b/docs/setup/upgrade.md @@ -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 +``` \ No newline at end of file diff --git a/template/amber/docs.amber b/template/amber/docs.amber index c1f7bbe4..827f9c69 100644 --- a/template/amber/docs.amber +++ b/template/amber/docs.amber @@ -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 diff --git a/template/amber/nodes.amber b/template/amber/nodes.amber index 0df94cdc..8b9ce853 100644 --- a/template/amber/nodes.amber +++ b/template/amber/nodes.amber @@ -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 diff --git a/template/amber/swagger.amber b/template/amber/swagger.amber index c8324e10..269235f8 100644 --- a/template/amber/swagger.amber +++ b/template/amber/swagger.amber @@ -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