Many docs in preparation of a new relase

fgrehm · fgrehm · commit fb9a6e6f0a5d · 2014-09-23T23:48:32.000-03:00
diff --git a/docs/buildpacks/custom.md b/docs/buildpacks/custom.md
@@ -5,18 +5,19 @@ In order to use a custom buildpack you can build your own images with it, or
 you can bind mount its directory with Devstep containers.
 
 For example, you can place your buildpack sources at `$HOME/projects/my-buildpack`
-and add the following line to your `$HOME/.devsteprc` so that it is available to
+and add the following line to your `$HOME/devstep.yml` so that it is available to
 all Devstep environments:
 
-```sh
-DEVSTEP_RUN_OPTS="${DEVSTEP_RUN_OPTS} -v $HOME/projects/my-buildpack:/.devstep/buildpacks/my-buildpack"
+```yaml
+volumes:
+  - '{{env "HOME"}}/projects/my-buildpack:/.devstep/buildpacks/my-buildpack'
 ```
 
 If you want to use a custom base image, you can add the following line to your
-project's `.devsteprc` or `$HOME/.devsteprc`:
+project's `devstep.yml` or `$HOME/devstep.yml`:
 
 ```sh
-DEVSTEP_SOURCE_IMAGE="my-user/an-image:a-tag"
+source_image: 'my-user/an-image:a-tag'
 ```
 
 For more information on creating buildpacks, please have a look at
diff --git a/docs/cli/aliases-and-binstubs.md b/docs/cli/aliases-and-binstubs.md
@@ -0,0 +1,29 @@
+# CLI Aliases and Binstubs
+
+The [`commands` configurations set from `devstep.yml` files](configuration)
+can be used to enable some powerful aliases in case you need to frequently
+run one off commands against a previously build project image.
+
+For example, you can keep a terminal session with a Rails server running on a
+tab and on a separate tab you can keep a `devstep hack` session open for
+development tasks so you can easily run tests or execute some `rake` tasks.
+
+By specifying the following command on your `devstep.yml` you'll be able to
+`devstep run server` instead of `devstep run -p 3000:3000 -- bundle exec rails server`:
+
+```yaml
+commands:
+  server:
+    cmd: ["bundle", "exec", "rails", "server"]
+    publish: ["3000:3000"]
+```
+
+## Using binstubs
+
+Given the configuration above, you might also want to skip the `devstep run`
+part from `devstep run server` while keeping the specified configs like published
+ports or volumes specified on `devstep.yml` files.
+
+By running the `devstep binstubs` command from your project's root, a bash script
+will be created under `.devstep/bin` for each specified command, so you are a `export PATH=".devstep/bin:$PATH"`
+away from running just `server` using the configs outlined above.
diff --git a/docs/cli/commands.md b/docs/cli/commands.md
@@ -1,14 +1,21 @@
 # CLI Commands
 --------------
 
-# TODO: Update to reflect the new yaml configs
+1. [Hack](#user-content-hack)
+1. [Build](#user-content-build)
+1. [Boostrap](#user-content-bootstrap)
+1. [Other commands](#user-content-other-commands)
 
-## `devstep hack`
+--------------
+
+## **Hack**
+
+**Command: `devstep hack [OPTIONS]`**
 
 This is the easiest way to get started with Devstep. By running the command
 from your project's root, Devstep will:
 
-1. Create a Docker container based on `fgrehm/devstep:v0.1.0` with project
+1. Create a Docker container based on `fgrehm/devstep:v0.2.0` with project
    sources bind mounted at `/workspace`.
 2. Detect and install project's dependencies on the new container using the
    available buildpacks.
@@ -17,15 +24,27 @@ from your project's root, Devstep will:
 Once you `exit` the `bash` session, the container will be garbage collected
 (aka `docker rm`ed).
 
-In case you need to provide additional parameters to the underlying `docker run`
-command you can use the `-r` flag. For example, `devstep hack -r "-p 80:8080"` will
-redirect the `8080` port on your host to the port `8080` within the container.
+**Options**
+
+* `-w, --working_dir` - Working directory inside the container
+* `-p, --publish` - Publish a container's port to the host (hostPort:containerPort)
+* `--link` - Add link to another container (name:alias)
+* `-e, --env` - Set environment variables
+* `--privileged` - Give extended privileges to this container
 
-## `devstep build`
+**Example**
+
+```sh
+devstep hack -p 80:8080 --link postgres:db --link memcached:mc -e DEVSTEP_BUNDLER_VERSION='1.6.0'
+```
+
+## **Build**
+
+**Command: `devstep build`**
 
 By running the command from your project's root, Devstep will:
 
-1. Create a Docker container based on `fgrehm/devstep:v0.1.0` with project
+1. Create a Docker container based on `fgrehm/devstep:v0.2.0` with project
    sources bind mounted at `/workspace`.
 2. Detect and install project's dependencies on the new container using the
    available buildpacks.
@@ -34,7 +53,7 @@ By running the command from your project's root, Devstep will:
 
 The `devstep/<PROJECT>` images act like snapshots of your project dependencies
 and will be used as the source image for subsequent `devstep` commands instead
-of the `fgrehm/devstep:v0.1.0` image.
+of the `fgrehm/devstep:v0.2.0` image.
 
 For example, running a `devstep hack` after building the image will use `devstep/<PROJECT>:latest`
 as the base container for new "hacking sessions" so that you don't have to build
@@ -52,7 +71,9 @@ on the host machine as a Docker volume in order to work on the project.
 docker run -ti -v `pwd`:/workspace devstep/<PROJECT>
 ```
 
-## `devstep bootstrap`
+## **Bootstrap**
+
+**Command: `devstep bootstrap [OPTIONS]`**
 
 As you might have guessed, this command can be used bootstrap new projects without
 cluttering your machine with development tools just to scaffold a new project.
@@ -62,11 +83,17 @@ bind mounted as `/workspace` on the container and you'll have to manually config
 the tools required to scaffold your new project. You can even force a specific
 buildpack to run from there.
 
+**Options**
+
+* `-r, --repository` - Repository name used when commiting the Docker image.
+
+**Example**
+
 For example, scaffolding a new Rails project means:
 
 ```sh
 cd $HOME/projects # or whatever directory you keep your projects
-devstep bootstrap -w my_app
+devstep bootstrap -r my_app
 
 build-project -b ruby
 reload-env
@@ -97,13 +124,13 @@ approach, replacing the Ruby / Rails specifics with the platform / framework
 of choice.
 
 
-## Other commands
+## **Other commands**
 
-* `clean` -> Remove all images built for the current project
-* `pristine` -> Rebuild current project associated Docker image from scratch
-* `run` -> Run a one off command against the current source image
-* `images` -> Display images available for the current project
-* `ps` -> List all containers associated with the current project
-* `info` -> Show some information about the current project
+* `info` - Show information about the current environment
+* `run` - Run a one off command against the current base image
+* `binstubs` - Generate binstubs for the commands specified on devstep.yml
+* `clean` - Remove previously built images for the current environment
+* `pristine` - Rebuild project image from scratch
+* `help, h` - Shows a list of commands or help for one command
 
 For the most up-to-date list of supported commands, run `devstep --help`.
diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md
@@ -1,56 +1,72 @@
 # CLI Configuration
 -------------------
 
-# TODO: Update to reflect the new yaml configs
-
-Devstep's CLI has a simple configuration mechanism in the form of Bash variables
-that can be used to customize its behavior globally or for a specific project.
-
-The available options along with its defaults are:
-
-```sh
-# Starting point for project images
-DEVSTEP_SOURCE_IMAGE="fgrehm/devstep:v0.1.0"
-
-# Root path to the project being built
-DEVSTEP_WORKSPACE_PATH=`pwd`
-
-# Name of the project being worked on
-DEVSTEP_WORKSPACE_NAME=$(basename ${DEVSTEP_WORKSPACE_PATH})
-
-# Name of Docker repository to use for the project
-DEVSTEP_WORKSPACE_REPO="devstep/${DEVSTEP_WORKSPACE_NAME}"
-
-# Host path for keeping devstep cached packages
-DEVSTEP_CACHE_PATH="/tmp/devstep/cache"
-
-# Global options for `docker run`s
-DEVSTEP_RUN_OPTS=
-
-# `devstep hack` specific options for `docker run`
-DEVSTEP_HACK_RUN_OPTS=
+Devstep's CLI has a configuration mechanism in the form of [YAML](http://www.yaml.org/)
+files that can be used to customize its behavior globally or for a specific project.
+
+The available options are described below:
+
+```yaml
+# The Docker repository to keep images built by devstep
+# DEFAULT: 'devstep/<CURRENT_DIR_NAME>'
+repository: 'repo/name'
+
+# The image used by devstep when building environments from scratch
+# DEFAULT: 'fgrehm/devstep:v0.2.0'
+source_image: 'source/image:tag'
+
+# The host cache dir that gets mounted inside the container at `/.devstep/cache`
+# for speeding up the dependencies installation process.
+# DEFAULT: '/tmp/devstep/cache'
+cache_dir: '{{env "HOME"}}/devstep/cache'
+
+# The directory where project sources should be mounted inside the container.
+# DEFAULT: '/workspace'
+working_dir: '/.devstep/gocode/src/github.com/fgrehm/devstep-cli'
+
+# Link to other existing containers (like a database for example).
+# Please note that devstep won't start the associated containers automatically
+# and an error will be raised in case the linked container does not exist or
+# if it is not running.
+# DEFAULT: <empty>
+links:
+- "postgres:db"
+- "memcached:mc"
+
+# Additional Docker volumes to share with the container.
+# DEFAULT: <empty>
+volumes:
+- "/path/on/host:/path/on/guest"
+
+# Environment variables.
+# DEFAULT: <empty>
+environment:
+  RAILS_ENV: "development"
+
+# Custom command aliases that can be used with `devstep run` to save some
+# typing. It is also used for generating project specific binstubs.
+# DEFAULT: <empty>
+commands:
+  # This can be run with `devstep run server`
+  server:
+    cmd: ["rails", "server"]
+    # Here you can use some of the configs described above
+    publish: ["3000:3000"]
+    volumes:
+    - '{{env "HOME"}}/certs/some-certificate.crt:/.devstep/some-certificate.crt'
+    - '{{env "HOME"}}/projects/some-gem-sources:/.devstep/some-gem-sources'
+    links:
+    - 'redis:redis'
+    environment:
+      RAILS_ENV: "hacking"
+  ruby:
+    # No custom options, used only for generating binstubs
 ```
 
 During a `devstep` command run, the CLI will start by loading global config
-options from `$HOME/.devsteprc` and project specific options from a `.devsteprc`
-file located on the directory where the command is run.
-
-Please note that to get project specific configs to be "merged" with global options
-for `docker run`s, you need to prepend your project configs with the previously
-defined value that might have been set on the global configuration file.
-
-For example, if you want to configure a project to always link a `devstep hack`
-container with a PostgreSQL database, you can add the following to your project's
-`.devsteprc`:
-
-```sh
-DEVSTEP_HACK_RUN_OPTS="${DEVSTEP_HACK_RUN_OPTS} --link postgresql:db"
-```
-
-To figure out what are the configured values for a specific project, you can run
-`devstep info`.
-
-## Disabling cache
+options from `$HOME/devstep.yml` and project specific options from a `devstep.yml`
+file located on the directory where the command is run and will merge them before
+creating containers.
 
-To disable the caching functionality you can set it to a blank string (`DEVSTEP_CACHE_PATH=""`)
-on your `$HOME/.devsteprc`.
+To figure out what are the configured values for a specific project after
+merging settings you can run `devstep info`.
diff --git a/docs/cli/installation.md b/docs/cli/installation.md
@@ -1,21 +1,22 @@
 # CLI Installation
 ------------------
 
-The CLI is a simple Bash script that you can download directly from a GitHub
-tagged release, place on a directory available on your `PATH` and make it
-executable.
+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`:
 
 ```sh
-# TODO: Update to new cli repo
-L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep/raw/v0.1.0/devstep > $L && chmod +x $L
+L=$HOME/bin/devstep && curl -sL https://github.com/fgrehm/devstep-cli/raw/v0.1.0/devstep > $L && chmod +x $L
 ```
 
-Please note that the CLI currently interacts with the `docker` command, so make
-sure you have it installed and that your user is capable to run `docker` commands
-[without `sudo`](http://docs.docker.io/installation/ubuntulinux/#giving-non-root-access).
+Please note that the CLI is currently limited 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.
+
 
 > **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
@@ -29,7 +30,13 @@ Docker adds support for user namespaces ([#6600](https://github.com/dotcloud/doc
 
 > 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 `DEVSTEP_SOURCE_IMAGE=<YOUR-IMAGE>`
-line to your `~/.devsteprc` so that the image is used as a source for your projects.
+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.
+
+## Bash autocomplete
+
+An autocompletion script can be installed using the one liner below:
 
-# TODO: Update above to reflect the new yaml configs
+```sh
+curl -sL https://github.com/codegangsta/cli/raw/master/autocomplete/bash_autocomplete | sed 's/$PROG/devstep/' | sudo tee /etc/bash_completion.d/devstep
+```
diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
@@ -0,0 +1,55 @@
+# CLI Plugins
+-----------
+
+Devstep's CLI has an experimental support for plugins in the form of JavaScript
+files that can be used to hook into the CLI runtime to modify its configuration
+at specific points during commands execution.
+
+Plugins should be installed to `$HOME/devstep/plugins/<PLUGIN_NAME>/plugin.js`
+on the machine that is executing `devstep` commands and the only requirement is
+that a plugin folder should have a `plugin.js` file.
+
+## Plugin API
+
+The current functionality is very rudimentary and is likely to be changed so right
+now it is best explained by the [squid3-ssl proxy](https://github.com/fgrehm/devstep-squid3-ssl)
+plugin source which is currently the plugin available:
+
+```js
+// `_currentPluginPath` is the host path where the JavaScript file is located
+// and is provided by Devstep's CLI plugin runtime, we keep its value on a
+// separate variable because its value gets changed for each plugin that
+// gets loaded.
+squidRoot = _currentPluginPath;
+
+// squidShared is the path were squid will keep both downloaded files on the host
+// machine and also the generated self signed certificate so that Devstep
+// containers can trust.
+squidShared = squidRoot + "/shared";
+
+// Hook into the `configLoaded` event that gets triggered right after configuration
+// files are loaded (eg: `$HOME/devstep.yml` and `CURRENT_DIR/devstep.yml`)
+devstep.on('configLoaded', function(config) {
+  config
+    // Link CLI created containers with the squid container
+    .addLink('squid3:squid3.dev')
+    // Share the certificate file with Devstep containers
+    .addVolume(squidShared + '/certs/squid3.dev.crt:/usr/share/ca-certificates/squid3.dev.crt')
+    .setEnv('HTTPS_PROXY_CERT', 'squid3.dev.crt');
+    // Inject the script that will trust the squid container certificate
+    .addVolume(squidRoot + '/proxy.sh:/etc/my_init.d/proxy.sh')
+
+    // Sets environmental variables so that programs make use of the cache
+    .setEnv('http_proxy', 'http://squid3.dev:3128')
+    .setEnv('https_proxy', 'http://squid3.dev:3128')
+});
+```
+
+The code above is the equivalent of passing in `-e`, `-v` and `--link` parameters
+to `devstep` commands.
+
+> The current functionality provided by the plugin runtime is pretty rudimentary
+so if you have ideas for other plugins that you think would be useful, feel free to
+reach out on the [CLI issue tracker](https://github.com/fgrehm/devstep-cli/issues/new)
+or on [Gitter](https://gitter.im/fgrehm/devstep) so that it can be further discussed
+as it will likely involve changes on the CLI itself.
diff --git a/docs/cli/tips.md b/docs/cli/tips.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
diff --git a/docs/template.html b/docs/template.html
