Add docker build option, mkdocs documentation (#264)

* Revise documentation

Author: rjanja

.gitignore

@@ -20,3 +20,6 @@ erl_crash.dump
 *.ez
 /_site
 /.sass-cache
+
+# Ignore virtualenv, used for building documentation
+/_venv

docs/about.md

@@ -0,0 +1,99 @@
+# Build Strategies
+
+Bootleg aims to cover the most common build strategies. Because the architecture on which your code runs must be the same as that with which your application was compiled, it's important to build your app in the right environment.
+
+## Supported build strategies
+
+### Local Machine
+
+To build your app on the same machine where you're running Bootleg, just set the `#!elixir :build_type` config option:
+
+!!! example "config/deploy.exs"
+    ```elixir
+    use Bootleg.DSL
+
+    config(:build_type, :local)
+    ```
+
+### Docker Container
+
+To build your app within a Docker container, create a Dockerfile that reproduces the server environment you are targeting.
+
+#### Create a Dockerfile
+
+Create a file named `Dockerfile.build` in your project directory.
+
+!!! note "Dockerfile.build"
+    ```docker
+    FROM ubuntu:16.04
+
+    ENV REFRESHED_AT=2018-08-16 \
+        LANG=en_US.UTF-8 \
+        HOME=/opt/build \
+        TERM=xterm
+
+    WORKDIR /opt/build
+
+    RUN \
+      apt-get update -y && \
+      apt-get install -y git wget vim locales && \
+      locale-gen en_US.UTF-8 && \
+      wget https://packages.erlang-solutions.com/erlang-solutions_1.0_all.deb && \
+      dpkg -i erlang-solutions_1.0_all.deb && \
+      rm erlang-solutions_1.0_all.deb && \
+      apt-get update -y && \
+      apt-get install -y erlang elixir
+
+    CMD ["/bin/bash"]
+    ```
+    The example here has been borrowed from Distillery's [excellent guide](https://hexdocs.pm/distillery/guides/building_in_docker.html).
+
+#### Build Docker Image
+
+A one-time build command is needed to set up your Docker image:
+
+```sh
+$ docker build -f Dockerfile.build -t elixir-ubuntu:latest .
+```
+
+#### Use Docker with Bootleg
+
+To tell Bootleg to use Docker, set the `#!elixir :build_type` and specify the image name in the `#!elixir :build_image` option:
+
+!!! example "config/deploy.exs"
+    ```elixir
+    use Bootleg.DSL
+
+    config(:build_type, :docker)
+    config(:build_image, "elixir-ubuntu:latest")
+    ```
+
+!!! info
+    If your project has local dependencies, they will not be automatically available from within the Docker image. To satisfy these dependencies you'll need to specify some other options. See [docker options](/reference/docker.md) for more information.
+
+### Remote Build Server
+
+In order to build your project remotely, Bootleg requires that your build server be set up to compile Elixir code. Make sure you have already installed Elixir and Erlang on any build server you define.
+
+To build your app on a remote build server, first define a `#!elixir :build` role:
+
+!!! example "config/deploy.exs"
+    ```elixir
+    use Bootleg.DSL
+
+    role :build, "build.example.com", user: "develop", workspace: "/some/build/workspace"
+    ```
+
+When defining a role, host options such as public key can also be supplied. See [roles and host options](roles.md) for more information.
+
+## Build your app
+
+To initiate the Build step, run the provided Mix task:
+
+```sh
+$ mix bootleg.build
+```
+
+!!! info
+    If your application doesn't build at this point, the errors should point you towards the problem. But don't worry too much about it for right now. We'll cover additional configuration in the following pages.
+

docs/config.md

@@ -0,0 +1,51 @@
+# Environments
+
+Bootleg has its own concept of environments, which is analogous to but different from `MIX_ENV`. Bootleg environments can be used if you have multiple clusters that you deploy your code to, such as a QA or staging cluster, in addition to
+your production cluster.
+
+## Configuration structure
+
+If you bootstrapped your config as detailed in the [Installing](/installing.md#set-up-bootleg) section the following files should already exist:
+
+    :::plain
+    mix.exs
+    ├── config/
+        ├── deploy.exs           # Main Bootleg config
+        └── deploy/
+            └── production.exs   # Environment-specific detail
+
+## Specifying a Bootleg environment
+
+To invoke a [Bootleg Mix Task](/reference/mix.md) with a specific environment, simply pass the name of the environment as the first argument. That environment's config file will be loaded immediately after `config/deploy.exs`.
+
+For example, say you have both a `production` and a `staging` cluster. Your configuration might look something like this:
+
+    :::plain
+    mix.exs
+    ├── config/
+        ├── deploy.exs
+        └── deploy/
+            ├── staging.exs
+            └── production.exs
+
+!!! example "Using the Staging Environment"
+    ```sh
+    $ mix bootleg.update staging
+    Starting remote build for staging environment
+    ```
+
+!!! example "Using the Production Environment"
+    ```sh
+    $ mix bootleg.update production
+    Starting remote build for production environment
+    ```
+
+The default environment is `production`, though this can be changed in your configuration.
+
+!!! example "Using the default Environment"
+    ```sh
+    $ mix bootleg.update
+    Starting remote build for production environment
+    ```
+
+

docs/config/build.md

@@ -0,0 +1,61 @@
+
+# Roles
+
+Actions in Bootleg are paired with roles, which are simply a collection of hosts that are responsible for the same function, for example building a release, archiving a release, or executing commands against a running application.
+
+Hosts can be grouped into one or more roles. Roles can be declared repeatedly to provide options to different sets of hosts.
+
+
+## Roles provided by Bootleg
+
+| Role | Description |
+|:---|:---|
+| `#!elixir :build` | Takes only one host. If a list is given, only the first host is used. |
+| `#!elixir :app` | Takes a list of hosts, or a string with one host. |
+
+## Defining your own roles
+
+By defining roles, you are defining responsibility groups to cross cut your host infrastructure. The `build` and
+`app` roles have inherent meaning to the default behavior of Bootleg, but you may also define more that you can later filter on when running commands inside a Bootleg hook. 
+
+Certain functionality or extensions may require additional roles, for example if your
+release needs to run Ecto migrations, you could assign a `#!elixir primary: true`
+option to one host and then filter on it.
+
+### Syntax
+
+The `role` macro requires both a name, specified as an atom, and a host or list of hosts. Any options you want to apply to those hosts can also be supplied.
+
+### Examples
+
+!!! example "Setting a different SSH option on a single host"
+    ```elixir
+    role :app, ["host1", "host2"], user: "deploy", identity: "/home/deploy/.ssh/deploy_key.priv"
+    role :app, "host2", port: 2222
+    ```
+    Two hosts are declared for the `app` role. Both will use a username of `deploy` and the same public key identity file. Only **host2** will use the non-standard port of *2222*.
+
+!!! example "Setting environment variables for the remote commands"
+    ```elixir
+    role :app, ["host1", "host2"], env: %{FOO: "bar", BIZ: "baz"}
+    ```
+    Two hosts are declared for the `app` role, both using environment variables set for any commands run remotely, `FOO=bar` and `BIZ=baz`.
+
+!!! example "Setting your own host options"
+    ```elixir
+    role :db, ["db.example.com", "db2.example.com"], user: "datadog"
+    role :db, "db.example.com", primary: true
+    ```
+    Two hosts are declared for the `db` role. Only `db.example.com` will receive an additional host-specific option for being the primary. Host options can be arbitrarily named and targeted by tasks.
+
+!!! example "Using an internal role option to change behavior"
+    Some host options are defined in Bootleg and have special meaning. `release_workspace` can be used when a single remote server is used to both build and run the application.
+    ```elixir
+    role :build, "example.com", workspace: "/home/deployer/builds", release_workspace: "/home/deployer"
+    role :app, "example.com", release_workspace: "/home/deployer"
+    ```
+    By specifying a `release_workspace` on the `:build` role, a release is placed in `/home/deployer` after it is built. By specifying a `release_workspace` on the `:app` role, that same release is copied from the `/home/deployer` directory to the app workspace.
+
+### Additional behaviors
+
+There is another built-in role `:all` which includes all hosts assigned to any role. `:all` is only available via `remote/2`.