docs: Update documentation to reflect latest changes and document how to install the CLI on OSX

Author: fgrehm

docs/buildpacks/golang.md

@@ -9,19 +9,24 @@ If a `Godep` dir is found, this buildpack will download and install [godep](http
 into your `$PATH` and will parse the `GoVersion` and `ImportPath` attributes
 when setting things up.
 
-Since currently devstep [does not support](https://github.com/fgrehm/devstep/issues/51)
-setting the workspace directory used inside the container, this buildpack will
-attempt to parse your project's import path for you using the following approach:
+This buildpack will attempt to identify your project's import path for you using
+the following priority:
 
 1. `ImportPath` from Godep configs
 2. `.godir` file
 3. Remote github repository URL
 4. `GO_PROJECT_NAME` environmental variable
 
 After identifying the import path, the buildpack will symlink your project sources
-into the appropriate path under the `$GOPATH/src` dir.
+into the appropriate path under the `$GOPATH/src` dir. You can also configure
+the `working_dir` to an appropriate path on your [project's `devstep.yml`](cli/configuration):
 
-If godep is configured, the buildpack will attempt a `godep go build` for you,
+```yml
+# The directory where project sources should be mounted inside the container.
+working_dir: '/home/devstep/gocode/src/github.com/fgrehm/devstep-cli'
+```
+
+If godep is configured, the buildpack will attempt a `godep go install` for you,
 otherwise it will download project's dependencies with `go get` so you can
 start hacking right away.
 

docs/cli/commands.md

@@ -3,7 +3,7 @@
 
 1. [Hack](#user-content-hack)
 1. [Build](#user-content-build)
-1. [Boostrap](#user-content-bootstrap)
+1. [Bootstrap](#user-content-bootstrap)
 1. [Other commands](#user-content-other-commands)
 
 --------------

docs/cli/installation.md

@@ -1,40 +1,43 @@
 # CLI Installation
 ------------------
 
-The CLI is [written in Golang](https://github.com/fgrehm/devstep-cli) and precompiled
-binaries are available for each GitHub tagged release. Installing it is a matter
-of downloading it from GitHub, placing the binary on a directory available on your
-`PATH` and making it executable.
-
-This one liner can handle it for you assuming that `$HOME/bin` is available
-on your `PATH`:
+Precompiled binaries are available for each GitHub tagged release:
 
 ```sh
+# On Linux (assumes `$HOME/bin` is on your `PATH`)
 L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep-cli/releases/download/v1.0.0/linux_amd64 > $L && chmod +x $L
+
+# On OSX
+brew tap fgrehm/devstep
+brew install devstep
 ```
 
-Please note that the CLI is currently limited to connecting to a local `/var/run/docker.sock`
+Please note that the CLI currently defaults to connecting to a local `/var/run/docker.sock`
 socket only and the user that runs `devstep` commands will need [non-root access to it](http://docs.docker.io/installation/ubuntulinux/#giving-non-root-access).
-Support for execution over TCP is likely to be added at some point.
-
+On OSX we rely on the environmental variables set by `docker-machine` (like
+`DOCKER_HOST` and `DOCKER_CERT_PATH` for example) and also on the fact that the
+`$HOME` dir is automagically shared with the VM that runs the docker daemon.
 
 > **IMPORTANT**: A `developer` user will be used by Devstep and it assumes your
-user and group ids are equal to `1000` when using the CLI or the container's init
-process will be aborted. This is to guarantee that files created within Docker
-containers have the appropriate permissions so that you can manipulate them
-on the host without the need to use `sudo`. This is currently a Devstep limitation
-that will be worked around in case there is enough demand or will be fixed once
-Docker adds support for user namespaces.
+user and group ids are equal to `1000` when using the CLI. This is to guarantee
+that files created within Docker containers have the appropriate permissions so
+that you can manipulate them on the host without the need to use `sudo`. This is
+currently a Devstep limitation that will be handled on a future release.
 
 > The `1000` id was chosen because it is the default uid / gid of Ubuntu Desktop users
 that are created during the installation process. To work around this limitation
 you can build your own image with the appropriate ids and add a `source_image: '<YOUR-IMAGE>:<OPTIONAL-TAG>'`
 line to your `~/devstep.yml` so that the image is used as a source for your projects.
 
+> When on OSX using dinghy, this should not be a problem thanks to how it sets up
+NFS shares.
+
 ## Bash autocomplete
 
-An autocompletion script can be installed using the one liner below:
+An autocompletion script for Linux can be installed using the one liner below:
 
 ```sh
 curl -sL https://github.com/codegangsta/cli/raw/master/autocomplete/bash_autocomplete | sed 's/$PROG/devstep/' | sudo tee /etc/bash_completion.d/devstep
 ```
+
+On OSX it gets installed automatically thanks to Homebrew.

docs/getting-started.md

@@ -12,45 +12,53 @@ will download that image as needed when using `Dockerfile`s but the Devstep CLI
 ---------------
 
 This project is being developed and tested on an Ubuntu 14.04 host with Docker
-1.7.0, while it is likely to work on other distros / Docker versions /
-[boot2docker](http://boot2docker.io/), I'm not sure how it will behave on the wild.
+1.9.0+ and on OSX using [dinghy VMs](https://github.com/codekitchen/dinghy) powered
+by the [xhyve docker-machine driver](https://github.com/zchee/docker-machine-driver-xhyve).
+While it is likely to work on other distros / Docker versions / boot2docker setups,
+I'm not sure how it will behave on the wild.
 
-Please note that the CLI is currently limited to connecting to a local `/var/run/docker.sock`
+Please note that the CLI currently defaults to connecting to a local `/var/run/docker.sock`
 socket only and the user that runs `devstep` commands will need [non-root access to it](http://docs.docker.io/installation/ubuntulinux/#giving-non-root-access).
-Support for execution over TCP is likely to be added at some point in the future.
+On OSX we rely on the environmental variables set by `docker-machine` (like
+`DOCKER_HOST` and `DOCKER_CERT_PATH` for example) and also on the fact that the
+`$HOME` dir is automagically shared with the VM that runs the docker daemon.
 
 ## Getting started with the CLI
 -------------------------------
 
 > **IMPORTANT**: A `developer` user will be used by Devstep and it assumes your
-user and group ids are equal to `1000` when using the CLI or the container's init
-process will be aborted. This is to guarantee that files created within Docker
-containers have the appropriate permissions so that you can manipulate them
-on the host without the need to use `sudo`. This is currently a Devstep limitation
-that will be worked around in case there is enough demand or will be fixed once
-Docker adds support for user namespaces.
+user and group ids are equal to `1000` when using the CLI. This is to guarantee
+that files created within Docker containers have the appropriate permissions so
+that you can manipulate them on the host without the need to use `sudo`. This is
+currently a Devstep limitation that will be handled on a future release.
 
 > The `1000` id was chosen because it is the default uid / gid of Ubuntu Desktop users
 that are created during the installation process. To work around this limitation
 you can build your own image with the appropriate ids and add a `source_image: '<YOUR-IMAGE>:<OPTIONAL-TAG>'`
 line to your `~/devstep.yml` so that the image is used as a source for your projects.
 
-To install the CLI, you can run the one liner below and read on for more:
+> When on OSX using dinghy, this should not be a problem thanks to how it sets up
+NFS shares.
+
+To install the CLI:
 
 ```sh
+# On Linux (assumes `$HOME/bin` is on your `PATH`)
 L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep-cli/releases/download/v1.0.0/linux_amd64 > $L && chmod +x $L
-```
 
-_The snippet above assumes `$HOME/bin` is on your `PATH`, change `$HOME/bin` to
-an appropriate path in case your system is not configured like that._
+# On OSX
+brew tap fgrehm/devstep
+brew install devstep
+```
 
 ### Doing a quick hack on a project
 
 With the CLI and Docker in place, just `cd` into your project and run `devstep hack`,
 it should be all you need to start working on your project. Devstep will create
 a Docker container, will install your project dependencies in it and at the end
 you'll be dropped on a `bash` session inside the container with project sources
-available at `/workspace`.
+available at `/workspace`. **Don't forget to `eval $(docker-machine env <vm-name>)` /
+`eval $(dinghy env)` in case you are on OSX.**
 
 From inside the container, you can do your work as you would on your own machine.
 For example, you can use `rake test` to run your Ruby tests or `go build` to
@@ -84,8 +92,8 @@ devstep hack -p 8080:8080
 ```
 
 And it will redirect the `8080` port on your host to the `8080` port within the
-container so you can just hit `http://localhost:8080` on your browser to see your
-app running after it is up.
+container so you can just hit `http://localhost:8080` (or `http://DOCKER_HOST:8080`)
+on your browser to see your app running after it is up.
 
 ### Using databases or other services from within containers
 

docs/introduction.md

@@ -52,8 +52,8 @@ Heroku apps) will be available for `fgrehm/devstep` environments.
 On top of `heroku/cedar:14`, we:
 
 * Create a `developer` user to avoid using `root` and creating files with wrong permissions during development.
-* Install some extra devel packages (like `libyaml-dev`) and other "nice to have"
-  packages and utilities (like `tmux` and `vim`).
+* Install some extra devel packages (like `libreadline`) and other "nice to have"
+  packages and utilities (like `vim` and `sqlite3`).
 * Configure PostgreSQL and MySQL clients.
 * Set the image `ENTRYPOINT` to our own init system and the default command to a `bash` login shell.
 * Configure a couple of startup scripts (like automatic port forwading to linked containers).