maybe finished install docs

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)

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

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
+Configure a single Docker host (1x build concurrency):
-[docker]
-nodes=[
-   "unix:///var/run/docker.sock",
-   "unix:///var/run/docker.sock"
-]
-```
 
 ```
 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_HOST_4="unix:///var/run/docker.sock"
-DOCKER_CERT
-DOCKER_KEY
-DOCKER_HOST
-DOCKER_HOST_*
 ```
 
-### 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_CA="/path/to/ca.pem"
-[docker]
+DOCKER_CERT="/path/to/cert.pem"
-nodes=[
+DOCKER_KEY="/path/to/key.pem"
-   "unix:///var/run/docker.sock"
-]
 ```
 
-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]
+DOCKER_HOST_1="tcp://1.2.3.4:2376"
-nodes=[
+DOCKER_HOST_2="tcp://1.2.3.4:2376"
-   "unix:///var/run/docker.sock",
+
-   "unix:///var/run/docker.sock",
+DOCKER_HOST_3="tcp://4.3.2.1:2376"
-   "unix:///var/run/docker.sock",
+DOCKER_HOST_4="tcp://4.3.2.1:2376"
-   "unix:///var/run/docker.sock"
+
-]
+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.
+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
-
-We recommend using this Gist to generate keys:
-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]
+DOCKER_CERT="/path/to/cert.pem"
-cert="/path/to/cert.pem"
+DOCKER_KEY="/path/to/key.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"
-]
 ```
 
-> 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 \

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

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

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:

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   \
+```