From 9fc02e360ad025bb4110160b11182bc1042c4e4d Mon Sep 17 00:00:00 2001 From: Brad Rydzewski Date: Fri, 10 Jul 2015 17:40:03 -0700 Subject: [PATCH] maybe finished install docs --- doc/setup/README.md | 6 ++- doc/setup/bitbucket.md | 4 +- doc/setup/docker.md | 96 ++++++++++++++++++++---------------------- doc/setup/github.md | 2 +- doc/setup/gitlab.md | 4 +- doc/setup/install.md | 2 + doc/setup/server.md | 39 +++++++++++++++++ 7 files changed, 98 insertions(+), 55 deletions(-) create mode 100644 doc/setup/server.md diff --git a/doc/setup/README.md b/doc/setup/README.md index d91ae314a..1bcdf5168 100644 --- a/doc/setup/README.md +++ b/doc/setup/README.md @@ -1,10 +1,12 @@ * [Install](#) * [Docker](install.md) -* [Remotes](#) +* [Setup](#) + * [Server](server.md) + * [Docker](docker.md) * [GitHub](github.md) * [GitLab](gitlab.md) * [Bitbucket](bitbucket.md) * [Database](#) * [SQLite](sqlite.md) - * [MySQL](mysql.md) * [Postgres](postgres.md) + * [MySQL](mysql.md) diff --git a/doc/setup/bitbucket.md b/doc/setup/bitbucket.md index e44bbcdb9..d4c1d7da2 100644 --- a/doc/setup/bitbucket.md +++ b/doc/setup/bitbucket.md @@ -1,3 +1,5 @@ +> **NOTE** Bitbucket integration has not yet been merged into 0.4, but is planned in the near future + # Bitbucket Drone comes with built-in support for Bitbucket. To enable and configure Bitbucket, you should set the following environment variables: @@ -13,7 +15,7 @@ BITBUCKET_ORGS="drone,drone-plugins" ## Bitbucket settings -This section lists all environment variables options used to configure Bitbucket. +This section lists all environment variables used to configure Bitbucket. * `BITBUCKET_KEY` oauth client id for registered application * `BITBUCKET_SECRET` oauth client secret for registered application diff --git a/doc/setup/docker.md b/doc/setup/docker.md index 41efa55cb..7444f235f 100644 --- a/doc/setup/docker.md +++ b/doc/setup/docker.md @@ -1,56 +1,53 @@ -Drone is configured to connect to the local Docker daemon. Drone will attempt to use the `DOCKER_HOST` environment variable to determine the daemon URL. If not set, Drone will attempt to use the default socket connection `unix:///var/run/docker.sock`. +# Docker -You can modify the Docker daemon URL in the Drone configuration file: +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. -```ini -[docker] -nodes=[ - "unix:///var/run/docker.sock", - "unix:///var/run/docker.sock" -] -``` +Configure a single Docker host (1x build concurrency): ``` DOCKER_HOST="unix:///var/run/docker.sock" +``` + +## Concurrency + +Configure Drone to run multiple, concurrent builds by increasing the number of registered Docker hosts. Each `DOCKER_HOST_*` environment variable will increase concurrency by 1. + +Configure multiple Docker hosts (4x build concurrency): + +``` 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_* +DOCKER_HOST_4="unix:///var/run/docker.sock" ``` -### Concurrency +Configure a single, external Docker host (1x build concurrency): -Each node is capable of processing a single build. Therefore, the below configuration will only execute one build at a time: +``` +DOCKER_HOST="tcp://1.2.3.4:2376" -```ini -[docker] -nodes=[ - "unix:///var/run/docker.sock" -] +DOCKER_CA="/path/to/ca.pem" +DOCKER_CERT="/path/to/cert.pem" +DOCKER_KEY="/path/to/key.pem" ``` -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: +Configure multiple, external Docker hosts (4x build concurrency using 2 remote servers): -```ini -[docker] -nodes=[ - "unix:///var/run/docker.sock", - "unix:///var/run/docker.sock", - "unix:///var/run/docker.sock", - "unix:///var/run/docker.sock" -] +``` +DOCKER_HOST_1="tcp://1.2.3.4:2376" +DOCKER_HOST_2="tcp://1.2.3.4:2376" + +DOCKER_HOST_3="tcp://4.3.2.1:2376" +DOCKER_HOST_4="tcp://4.3.2.1:2376" + +DOCKER_CA="/path/to/ca.pem" +DOCKER_CERT="/path/to/cert.pem" +DOCKER_KEY="/path/to/key.pem" ``` -### Distribution +## Remote Servers -As your installation grows you may need to distribute your builds across multiple servers. Since Docker exposes a REST API we can easily configure Drone to communicate with remote servers. First we'll need to generate an SSL certificate in order to secure communication across nodes. - -We recommend using this Gist to generate keys: -https://gist.github.com/bradrydzewski/a6090115b3fecfc25280 +Connecting to remote Docker servers requires TLS authentication for security reasons. You will therefore need to generate your own self-signed certificates. For convenience, we've created the following gist to help generate a certificate: https://gist.github.com/bradrydzewski/a6090115b3fecfc25280 This will generate the following files: @@ -60,32 +57,31 @@ This will generate the following files: * server-cert.pem * server-key.pem -Update your Drone configuration to use the `cert.pem` and `key.pem` files and remote daemon URLs: +Tell Drone where to find the `cert.pem` and `key.pem`: -```ini -[docker] -cert="/path/to/cert.pem" -key="/path/to/key.pem" -nodes = [ - "tcp://172.17.42.1:2376", - "tcp://172.17.42.2:2376", - "tcp://172.17.42.3:2376", - "tcp://172.17.42.4:2376" -] +``` +DOCKER_CERT="/path/to/cert.pem" +DOCKER_KEY="/path/to/key.pem" ``` -> Remember that you can add the same URL multiple times to increase concurrency! +If you are running Drone inside Docker you will need to mount the volume containing the certificate: -Finally, you need to place the server key, certificate and ca on each remote server. You'll need to update the Docker daemon configuration on each remote server (in `/etc/init/drone-dart.conf`) and restart Docker: +``` +docker run + --volume /path/to/cert.pem:/path/to/cert.pem \ + --volume /path/to/key.pem:/path/to/key.pem \ +``` + +Tell Docker where to find the certificate files. Install the certificates on every remote machine (in `/etc/ssl/docker/`) and update each Docker configuration file (at `/etc/init/drone-dart.conf`) accordingly: ```bash # Use DOCKER_OPTS to modify the daemon startup options. DOCKER_OPTS="--tlsverify --tlscacert=/etc/ssl/docker/ca.pem --tlscert=/etc/ssl/docker/server-cert.pem --tlskey=/etc/ssl/docker/server-key.pem -H=0.0.0.0:2376 -H unix:///var/run/docker.sock" ``` -Lastly, we can verify that everything is configured correctly. We can try to connect to a remote Docker server from our Drone server using the following command: +Verify that everything is configured correctly by connecting to a remote Docker server from our Drone server using the following command: -```bash +``` sudo docker \ --tls \ --tlscacert=/path/to/ca.pem \ diff --git a/doc/setup/github.md b/doc/setup/github.md index 2d8b67775..a18f1131a 100644 --- a/doc/setup/github.md +++ b/doc/setup/github.md @@ -11,7 +11,7 @@ GITHUB_SECRET="1ac1eae5ff1b490892f5" ## GitHub settings -This section lists all environment variables options used to configure GitHub. +This section lists all environment variables used to configure GitHub. * `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 diff --git a/doc/setup/gitlab.md b/doc/setup/gitlab.md index c26bdea06..741dc5706 100644 --- a/doc/setup/gitlab.md +++ b/doc/setup/gitlab.md @@ -1,3 +1,5 @@ +> **NOTE** GitLab integration has not yet been merged into 0.4, but is planned in the near future + # GitLab Drone comes with built-in support for GitLab 7.7 and higher. To enable and configure GitLab, you should set the following environment variables: @@ -15,7 +17,7 @@ GITLAB_SKIP_VERIFY="false" ## GitLab settings -This section lists all environment variables options used to configure GitLab. +This section lists all environment variables used to configure GitLab. * `GITLAB_HOST` server address to connect to. * `GITLAB_CLIENT` oauth client id for registered application diff --git a/doc/setup/install.md b/doc/setup/install.md index 873a186ba..1f7bb220e 100644 --- a/doc/setup/install.md +++ b/doc/setup/install.md @@ -1,3 +1,5 @@ +> **NOTE** we are not yet producing an image for 0.4 so this section does not work as documented. An official image for the 0.4 release is coming soon + # 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: diff --git a/doc/setup/server.md b/doc/setup/server.md new file mode 100644 index 000000000..2104001e7 --- /dev/null +++ b/doc/setup/server.md @@ -0,0 +1,39 @@ +# Server + +Drone uses the `net/http` package in the Go standard library for high-performance `http` request processing. This section describes how to customize the default server configuration. This section is completely **optional**. + +## Server Settings + +This section lists all environment variables used to configure the server. + +* `SERVER_ADDR` server address and port. Defaults to `:8000` +* `SERVER_KEY` ssl certificate key (key.pem) +* `SERVER_CERT` ssl certificate (cert.pem) + +This example changes the default port to `:80`: + +``` +SERVER_ADDR=":80" +``` + +## Server SSL + +Drone uses the `ListAndServerTLS` 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). + +This example accepts `HTTPS` connections: + +``` +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 running Drone inside Docker, you'll need to mount the volume containing the certificate: + +``` +docker run + --volume /path/to/cert.pem:/path/to/cert.pem \ + --volume /path/to/key.pem:/path/to/key.pem \ +```