cide 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a5a4fe8da41d9c191605ec959cf7c333cf14f170
-  data.tar.gz: b62108bf438c8cbc65ae418014bec5a6f572362f
+  metadata.gz: f7abefe36a37940197b6aadd1fcb7df51562fde0
+  data.tar.gz: 5a4c14225d5fa5a7a3331c2c4eede54f0a1ad661
 SHA512:
-  metadata.gz: 23171d6c97f0b00a3dcbb9931a098f276c15784e985fe4f05dd6a45013a464fbede08752cbf2d700139d251188cde6cd6361d288a5b338facff86206742627d3
-  data.tar.gz: 882a92b8e9e3b3b0905f5c22e6889c42040191757f770bbe47dc7e349330895efebf12fb78ea81d4a3bebce363e38fd9cd280dcc51da38ca9deb117ed51139d6
+  metadata.gz: 6610a43e9ed60f4f8e2addfdf7ae204b82ef082971b1555e333d69e88afb51ebcb8a04b576b080cbb3172dc7215613a48d8e2bb17e2f62fc7e0e47b544984bd6
+  data.tar.gz: 4f294c94689281c3195997dd036c0f1ca66a63b5f05e489e3d99cef09539d035d6197391d23975ace077cde710f7558a7ea5ca0be3d9ce4398508f7f4521863e

data/.gitignore

@@ -1 +1,4 @@
 *.gem
+man/*.1
+man/*.css
+man/*.html

data/CHANGELOG.md

@@ -1,4 +1,10 @@
 
+0.5.0 / 2015-06-19
+==================
+
+  * NEW: man pages and doc !
+  * CHANGE: config file is `cide.yml` instead of `.cide.yml`
+
 0.4.1 / 2015-06-02
 ==================
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cide (0.4.1)
+    cide (0.5.0)
       thor (~> 0.19)
       virtus (~> 1.0)
 
@@ -21,6 +21,8 @@ GEM
       descendants_tracker (~> 0.0.4)
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
+    binman (4.0.0)
+      opener (>= 0.1.0, < 1)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
     descendants_tracker (0.0.4)
@@ -30,12 +32,17 @@ GEM
     i18n (0.7.0)
     ice_nine (0.11.1)
     json (1.8.1)
+    md2man (4.0.0)
+      binman (~> 4.0)
+      redcarpet (~> 3.0)
     minitest (5.4.3)
+    opener (0.1.0)
     parser (2.2.0.3)
       ast (>= 1.1, < 3.0)
     powerpack (0.1.0)
     rainbow (2.0.0)
     rake (10.4.2)
+    redcarpet (3.3.1)
     rspec (3.2.0)
       rspec-core (~> 3.2.0)
       rspec-expectations (~> 3.2.0)
@@ -72,6 +79,10 @@ PLATFORMS
 DEPENDENCIES
   activesupport
   cide!
+  md2man
   rake
   rspec
   rubocop
+
+BUNDLED WITH
+   1.10.3

data/README.md

@@ -1,21 +1,21 @@
-*cide* - Continuous Integration Docker Environment
-================================================
+*cide* - Isolated test runner with Docker
+=========================================
 
 *cide* is a command-line tool that runs tests in an isolated (docker)
 environment. It solves a problem where Jenkins workers need all the project's
 dependencies (possibly conflicting) to be installed on the boxes. With *cide*
 each run gets it's own set of temporary docker containers which are scratched
-at the end. Incidentally it's also possible to the the same `cide` command on
-the developer machine and get the same build environent as on the CI. This
-makes configuration iterations much shorter and allow to converge on a working
-configuration faster.
+at the end. Incidentally it's also possible to run the same `cide` command on
+the developer machine and get the same build environment as on the CI. This
+makes configuration iterations much shorter and allows to converge on a
+working configuration faster.
 
 Usage
 -----
 
 Go to the target project's root and run `cide init` to populate a default
-`.cide.yml`. This file contains all the instruction to build your project with
-cide.
+`cide.yml`. This file contains all the instruction to build your project with
+cide and is [documented here](docs/cide.yml.md).
 
 Once the file is configure run `cide` to execute the build. All the output
 will appear in the console.
@@ -23,7 +23,7 @@ will appear in the console.
 Example
 -------
 
-`.cide.yml`
+`cide.yml`
 ```yaml
 ---
 from: "ruby:2.1"
@@ -55,6 +55,7 @@ Missing features
   current format might be a bit daunting for non-experts.
 * Build matrix: run variations of the tests, for example with different
   versions of ruby to make sure all are supported (useful for libraries).
+* Support for local docker machine
 
 PR welcome !
 
@@ -89,8 +90,6 @@ Similar projects
 TODO
 ----
 
-* Document the `.cide.yml` format. Look into `lib/cide/build/config_loader.rb`
-  for now
 * Explain how to use *cide* with Jenkins
 * Explain Travis CI vs *cide* + Jenkins
 

data/Rakefile

@@ -1,7 +1,8 @@
-require 'rubocop/rake_task'
+require 'md2man/rakefile'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
-task default: [:spec, :rubocop]
+task default: [:spec, :rubocop, 'md2man:man']
 
 RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new

data/bin/cide

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 #
-# cide - Continuous Integration Docker Environment
+# cide - Isolated test runner with Docker
 #
 
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
-require 'cide'
+require 'cide/cli'
 CIDE::CLI.start

data/cide.gemspec

@@ -2,13 +2,14 @@
 
 Gem::Specification.new do |s|
   s.name          = 'cide'
-  s.version       = '0.4.1'
+  s.version       = '0.5.0'
   s.authors       = ['zimbatm']
   s.email         = ['zimbatm@zimbatm.com']
-  s.summary       = 'CI docker runner'
+  s.summary       = 'Isolated test runner with Docker'
   s.description   = <<DESC
-cide makes it easy to reproduce CI builds on the developer computer by
-providing the same docker environment.
+cide is a command-line tool that runs tests in an isolated (docker)
+environment. It allows to run the same command on the developer and CI
+machines.
 DESC
   s.homepage      = 'https://github.com/zimbatm/cide'
   s.license       = 'MIT'
@@ -22,8 +23,9 @@ DESC
 
   s.add_runtime_dependency 'thor', '~> 0.19'
   s.add_runtime_dependency 'virtus', '~> 1.0'
+  s.add_development_dependency 'activesupport'
+  s.add_development_dependency 'md2man'
   s.add_development_dependency 'rake'
-  s.add_development_dependency 'rubocop'
   s.add_development_dependency 'rspec'
-  s.add_development_dependency 'activesupport'
+  s.add_development_dependency 'rubocop'
 end

data/{.cide.yml → cide.yml}

@@ -8,5 +8,4 @@ before:
     - Gemfile.lock
     - cide.gemspec
   run: bundle install --jobs=3 --retry=3 --deployment
-use_ssh: false
 run: bundle exec rake

data/docs/cide.yml.md

@@ -0,0 +1,154 @@
+CIDE.YML 1 "JUNE 2015" cide.yml "Cide Manual"
+=============================================
+
+NAME
+----
+
+cide.yml - file format that directs the `cide build` execution
+
+DESCRIPTION
+-----------
+
+The `cide.yml` file is encoded in the [YAML markup language](http://yaml.org/)
+and describes mostly how the Dockerfile will be generated.
+
+It has the following semantic:
+
+Root document
+-------------
+
+```yaml
+---
+# Image to base the build on
+#
+# required
+# type: string
+from: 'ubuntu'
+
+# A step executed as root. See the Step definition.
+as_root: {}
+
+# If set to true, inject the invoker's SSH key into the image.
+# This is used for shared github access for example.
+#
+# type: boolean
+use_ssh: no
+
+# A step executed as the "cide" user. See the Step definition.
+before: {}
+
+# Environment variables set at runtime. See the ENV definition.
+env: {}
+
+# Selects a file or directory to export. When set and cide is invoked with
+# --export the same directory will be copied back into the project's root.
+#
+# type: string
+export_dir:
+
+# When defined, executes and attaches the defined linked containers to the
+# CI runtime. See the Link definition.
+links: []
+
+# Determines what script to run to execute the tests. This is the main command
+# that is used to run the CI.
+#
+# The script has to exit with an exit-status of zero to succeed.
+#
+# default: "script/ci"
+# type: string
+run: rake
+```
+
+Step definition
+---------------
+
+Here is the format for a step.
+
+```yaml
+# An array or hash of files to add
+#
+# In the hash form, the target is on the left-hand side and source on the
+# right-hand side. If multiple values are passed on to the right then they are
+# all added to the same folder.
+#
+# If a URL is provided in the source it is fetched during the build.
+#
+# Note that source files should either come from a URL or from a file within
+# the project's directory.
+add:
+  /etc/cacert.pem: http://curl.se/cacert.pem
+  /src:
+    - Gemfile
+    - Gemfile.lock
+# or
+add:
+  - one
+  - two
+
+# Sets environment variables in this step (and next ones). See the ENV
+# definition.
+env: {}
+
+# A list of commands to run in that stage
+#
+# type: string or array of string
+run:
+  - bundle exec
+  - npm install
+# or
+run: go get ./...
+```
+
+If the step is defined as a string or array, those are interpreted as commands
+to add to that step.
+
+ENV definition
+--------------
+
+An array or hash of environment variables to load
+
+In the hash for, the left-hand side is the key and the right-hand side the
+value.
+
+If a hash value is nil or the array form is used, the environment variables
+are loaded from the cide invoker environment.
+
+```yaml
+env:
+  HOME: /cide
+  AWS_ACCESS_KEY_ID:
+# or
+env:
+  - AWS_ACCESS_SECRET_KEY
+```
+
+Link definition
+---------------
+
+A hash that describes a linked containers. Linked containers are automatically
+started before executing the main command and destroyed after that.
+
+```yaml
+# Gives a name to the container to execute. This also determines the hostname
+# the main container will be able to address this container with.
+#
+# If the name is missing, the name is extracted from the `from` key. For
+# example if the `from` value is "foobar/redis:2.6" the name will be "redis"
+#
+# type: string
+name: 'mysql'
+
+# Name of the image to pull and base the container on.
+#
+# type: string
+name: 'redis:2.6'
+
+# Environment variables for that container. See the ENV definition.
+env: {}
+
+# Single command to execute the container with.
+#
+# type: string
+run: 'redis-server'
+```

data/docs/sidebar.md

@@ -0,0 +1,22 @@
+# cide
+
+[ditto:searchbar]
+- [Home]()
+- [CHANGELOG](#/CHANGELOG)
+- [LICENSE (MIT)](#/LICENSE)
+
+## Github
+
+- [Repo](https://github.com/zimbatm/cide)
+- [Issues](https://github.com/zimbatm/cide/issues)
+- [Releases](https://github.com/zimbatm/cide/releases)
+- [Wiki](https://github.com/zimbatm/cide/wiki)
+
+## Man pages
+- [man 1 cide](#man/cide.1)
+- [man 1 cide-build](#man/cide-build.1)
+- [man 1 cide-clean](#man/cide-clean.1)
+- [man 1 cide-debug](#man/cide-debug.1)
+- [man 1 cide-init](#man/cide-init.1)
+- [man 1 cide.yml](#man/cide.yml.1)
+

data/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>cide - Isolated test runner with Docker</title>
+
+  <!-- jQuery -->
+  <script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
+  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.min.js"></script>
+
+  <!-- marked -->
+  <script src="//chutsu.github.io/ditto/ver/0.12/marked.js"></script>
+
+  <!-- highlight -->
+  <link rel="stylesheet" href="//chutsu.github.io/ditto/ver/0.12/github.css"> 
+  <script src="//chutsu.github.io/ditto/ver/0.12/highlight.js"></script>
+
+  <!-- ditto -->
+  <link rel="stylesheet" href="//chutsu.github.io/ditto/ver/0.12/ditto.css">
+  <script src="//chutsu.github.io/ditto/ver/0.12/ditto.js"></script>
+</head>
+<body>
+  <!-- essential -->
+  <div id="sidebar"></div>
+  <div id="content"></div>
+  <div id="hide"></div>
+
+  <!-- optional -->
+  <div id="back_to_top">back to top</div>
+  <div id="edit">edit</div>
+  <div id="loading">Loading ...</div>
+  <div id="error"></div>
+
+  <script>
+    $(function($) {
+      // essential settings
+      ditto.index = "README.md";
+      ditto.sidebar_file = "docs/sidebar.md";
+
+      // optional settings if you want github search
+      ditto.github_username = "zimbatm";
+      ditto.github_repo = "cide";
+      ditto.highlight_code = true;
+
+      // where the docs are actually stored on github - so you can edit
+      ditto.base_url = "https://github.com/zimbatm/cide/edit/master";
+
+      // run
+      ditto.run();
+    });
+  </script>
+</body>
+</html>

data/lib/cide/build/config.rb

@@ -70,6 +70,11 @@ module CIDE
         ERB.new(File.read(DOCKERFILE_TEMPLATE), nil, '<>-').result(binding)
       end
 
+      def self.load(dir = Dir.pwd, output = $stderr)
+        file_path = find_config(dir)
+        load_file(file_path, output)
+      end
+
       def self.load_file(file_path, output = $stderr)
         obj = new
         loader = ConfigLoader.new(obj)
@@ -86,6 +91,13 @@ module CIDE
         return obj if obj.errors.empty?
         nil
       end
+
+      def self.find_config(dir)
+        paths = CONFIG_FILES.map { |name| File.expand_path(name, dir) }
+        paths
+          .find { |path| File.exist?(path) } ||
+          fail("Config not found among these paths: #{paths.inspect}")
+      end
     end
   end
 end

data/lib/cide/cli.rb

@@ -21,7 +21,7 @@ module CIDE
 
     method_option 'name',
       desc: 'Name of the build',
-      aliases: %w(n t),
+      aliases: %w(-n -t),
       default: File.basename(Dir.pwd)
 
     method_option 'export',
@@ -31,13 +31,13 @@ module CIDE
 
     method_option 'export_dir',
       desc: 'Change the ouput directory on the host',
-      aliases: %w(o host_export_dir),
+      aliases: %w(-o --host_export_dir),
       default: nil
 
     method_option 'run',
       desc: 'Override the script to run',
       type: :array,
-      aliases: ['r'],
+      aliases: ['-r'],
       default: []
 
     method_option 'pull',
@@ -47,7 +47,7 @@ module CIDE
 
     method_option 'ssh_key',
       desc: 'Path to a ssh key to import into the docker image',
-      aliases: ['s'],
+      aliases: ['-s'],
       default: '~/.ssh/id_rsa'
 
     def build
@@ -57,7 +57,7 @@ module CIDE
 
       ## Config ##
       banner 'Config'
-      build = Build::Config.load_file CONFIG_FILE
+      build = Build::Config.load(Dir.pwd)
       exit 1 if build.nil?
       export_dir = options.export_dir
       export_dir ||= File.dirname(build.export_dir) if build.export_dir
@@ -161,7 +161,7 @@ module CIDE
     desc 'debug', 'Opens a debug console in the last project image'
     method_option 'name',
       desc: 'Name of the build',
-      aliases: %w(n t),
+      aliases: %w(-n -t),
       default: File.basename(Dir.pwd)
     method_option 'user',
       desc: 'User to run under',
@@ -173,7 +173,7 @@ module CIDE
 
       ## Config ##
       banner 'Config'
-      build = Build::Config.load_file CONFIG_FILE
+      build = Build::Config.load
       exit 1 if build.nil?
       name = CIDE::Docker.id options.name
       tag = "cide/#{name}"
@@ -270,10 +270,10 @@ module CIDE
       docker('rmi', '--force', *old_cide_images)
     end
 
-    desc 'init', "Creates a blank #{CONFIG_FILE} into the project"
+    desc 'init', "Creates a blank #{CONFIG_FILES.first} into the project"
     def init
-      puts "Creating #{CONFIG_FILE} with default values"
-      create_file CONFIG_FILE, File.read(DEFAULT_CIDEFILE)
+      puts "Creating #{CONFIG_FILES.first} with default values"
+      create_file CONFIG_FILES.first, File.read(DEFAULT_CIDEFILE)
     end
 
     private

data/lib/cide/constants.rb

@@ -5,7 +5,7 @@ module CIDE
   TEMP_SSH_KEY = 'id_rsa.tmp'
   SSH_CONFIG_FILE = 'ssh_config'
   SSH_CONFIG_PATH = File.join(dir, SSH_CONFIG_FILE)
-  CONFIG_FILE = '.cide.yml'
+  CONFIG_FILES = ['cide.yml', '.cide.yml']
   CIDE_DIR = '/cide'
   CIDE_SRC_DIR = File.join(CIDE_DIR, 'src')
   CIDE_SSH_DIR = File.join(CIDE_DIR, '.ssh')

data/man/cide-build.1.md

@@ -0,0 +1,62 @@
+CIDE-BUILD 1 "JUNE 2015" cide-build "Cide Manual"
+=================================================
+
+NAME
+----
+
+cide-build - Builds an image and executes the run script
+
+SYNOPSIS
+--------
+
+*cide build* [`-n`|`--name`=<*name*>] [`--export`|`--no-export`]
+             [`-o`|`--export-dir`=<*path*>] [`-r`|`--run`=<*command*>]
+             [`--pull`|`--no-pull`] [`-s`|`--ssh-key`=<*path*>]
+
+DESCRIPTION
+-----------
+
+This is the default command that does most of the work and is invoked 99% of
+the command.
+
+When invoked it will read the `cide.yml` file, generate a temporary
+`Dockerfile.cide` file, build it with *docker build*, start all the linked
+containers and finally run the selected script. When that script exits all the
+running containers are torn down. This loop guarantees a blank slate for every
+CI run with isolated dependencies.
+
+OPTIONS
+-------
+
+`-n`, `--name`=<*name*>
+  Name of the built image. This can be used to differentiate between branches
+  or others in a CI environment. By default the name is the basename(1) of the
+  current directory.
+
+`--export`, `--no-export`
+  Whenever to export artifacts. If `--export` is passed and the `export:`
+  directive is set in the `cide.yml` file, artifacts from that directory are
+  transfered back outside of the container and into the current directory.
+
+`-o`, `--export-dir`=<*path*>
+  By default the export directory is the same as the one given in the
+  `export:` directive in the `cide.yml` file. It's possible to change that
+  target folder outside of the container.
+
+`-r`, `--run`=<*command*>
+  Override the script to run. Usually the `run:` directive in the `cide.yml`
+  is defining what to run but this could be used for a quick one-off.
+
+`--pull`, `--no-pull`
+  Whenever to pull for new images on build. If set it will try to fetch new
+  versions of the `from:` directive. It can be useful to get new versions of
+  an image but also invalidates all the cache.
+
+`-s`, `--ssh-key`=<*path*>
+  When the `use_ssh:` directive is set to true, where to get the ssh key to
+  inject into the container. Defaults to `~/.ssh/id_rsa`.
+
+SEE ALSO
+--------
+
+cide(1), cide.yml(1)

data/man/cide-clean.1.md

@@ -0,0 +1,34 @@
+CIDE-CLEAN 1 "JUNE 2015" cide-clean "Cide Manual"
+=================================================
+
+NAME
+----
+
+cide-clean - Removes old containers
+
+SYNOPSIS
+--------
+
+*cide clean* [`--days`=<*n*>] [`--count`=<*n*>]
+
+DESCRIPTION
+-----------
+
+`cide` can generate a lot of data on the box in terms of docker images and
+containers. This command tries to removes old images with a simple heuristic.
+
+*NOTE*: This command might interfer with other users of the docker daemon.
+
+OPTIONS
+-------
+
+`--days`=<*n*>
+  Number of days to keep the images. Defaults to 7
+
+`--count`=<*n*>
+  Maximum number of images to keep. Defaults to 10
+
+SEE ALSO
+--------
+
+cide(1)

data/man/cide-debug.1.md

@@ -0,0 +1,42 @@
+CIDE-DEBUG 1 "JUNE 2015" cide-debug "Cide Manual"
+=================================================
+
+NAME
+----
+
+cide-debug - Opens a debug console in the last project image
+
+SYNOPSIS
+--------
+
+*cide debug* [`-n`|`--name`=<*name*>] [`--user`=<*username*>]
+
+DESCRIPTION
+-----------
+
+Sometimes it's useful to run commands inside of the same environment where the
+CI tests are run from. For example if an error doesn't reproduce on the
+developer's machine.
+
+*cide debug* starts a new temporary container (and linked containers) in the
+previously generated container. This requires the user to have run *cide
+build* previously.
+
+OPTIONS
+-------
+
+`-n`, `--name`=<*name*>
+  Name of the image. This is generally not required unless a name has been
+  given during the *cide build* phase as well.
+
+  Defaults to the basename(1) of the current directory.
+
+`--user`=<*username*>
+  Selects the user to run the container under. By default the `cide` user is
+  selected. In some situations it's useful to run the container as `root`
+  (when poking at system dependencies)
+
+SEE ALSO
+--------
+
+cide(1)

data/man/cide-init.1.md

@@ -0,0 +1,29 @@
+CIDE-INIT 1 "JUNE 2015" cide-init "Cide Manual"
+=================================================
+
+NAME
+----
+
+cide-init - Creates a blank `cide.yml` into the project
+
+SYNOPSIS
+--------
+
+*cide init*
+
+DESCRIPTION
+-----------
+
+It's useful to get a basic skeleton when adding *cide* to a new project.  If
+the file already exists a confirmation is asked.
+
+FILES
+-----
+
+*cide.yml*
+  Per project build and test settings. See cide.yml(1)
+
+SEE ALSO
+--------
+
+cide(1), cide.yml(1)

data/man/cide.1.md

@@ -0,0 +1,113 @@
+CIDE 1 "JUNE 2015" cide "Cide Manual"
+======================================
+
+NAME
+----
+
+cide - Isolated test runner with Docker
+
+SYNOPSIS
+--------
+
+*cide* [`-f`|`--force`] [`-p`|`--pretend`|`--no-pretend`]
+     [`-q`|`--quiet`|`--no-quiet`] [`-s`|`--skip`|`--no-skip`]
+     <*command*> [<*args*>]
+
+DESCRIPTION
+-----------
+
+*cide* is a command-line tool that executes tests in isolation using a
+container (through Docker).
+
+The default *cide build* command reads a `.cide.yml` file in the current
+folder and takes it's content to build a temporary Dockerfile that imports all
+of the current directory's structure, builds an image with it and then runs a
+container from it that executes the specified tests. See the cide.yml(1) man
+page for the structure of that file.
+
+OPTIONS
+-------
+
+These are global options that set the behavior of all commands.
+
+`-f`, `--force`
+  Overwrite files that already exist
+
+`-p`, `--pretend`, `--no-pretend`
+  Run but do not make any changes
+
+`-q`, `--quiet`, `--no-quiet`
+  Suppress status output
+
+`-s`, `--skip`, `--no-skip`
+  Skip files that already exist
+
+COMMANDS
+--------
+
+*cide build* [<*options*>]
+  Builds an image and executes the run script. This is the default command
+  when none is provided.
+
+  See cide-build(1)
+
+*cide clean* [<*options*>]
+  Removes old containers.
+
+  See cide-clean(1)
+
+*cide debug* [<*options*>]
+  Opens a debug console in the last project image
+
+  See cide-debug(1)
+
+*cide help* [<*command*>]
+  Shows the general help or the one for the given *command*
+
+*cide init*
+  Creates a blank `cide.yml` file into the project.
+
+  See cide-init(1)
+
+FILES
+-----
+
+*cide.yml*
+  Per project build and test settings. See cide.yml(1)
+
+ENVIRONMENT
+-----------
+
+The following environment variables are used by the `docker` client to connect
+to the `docker` daemon. See also
+https://docs.docker.com/docker/reference/commandline/cli/#environment-variables:b659b046131d4024ab5e2d3675716bf0
+
+*DOCKER_HOST*
+  Daemon socket to connect to.
+
+*DOCKER_CERT_PATH*
+  The location of your authentication keys.
+
+*DOCKER_TLS_VERIFY*
+  When set Docker uses TLS and verifies the remote.
+
+CONTRIBUTE
+----------
+
+Bug reports, contributions and forks are welcome.
+
+All bugs or other forms of discussion happen on
+<http://github.com/zimbatm/cide/issues>
+
+There is also a wiki available where you can share your usage patterns or
+other tips and tricks <https://github.com/zimbatm/cide/wiki>
+
+COPYRIGHT
+---------
+
+Copyright (C) 2015 zimbatm and contributors under the MIT licence.
+
+SEE ALSO
+--------
+
+cide.yml(1)

data/man/cide.yml.1.md

@@ -0,0 +1,154 @@
+CIDE.YML 1 "JUNE 2015" cide.yml "Cide Manual"
+=============================================
+
+NAME
+----
+
+cide.yml - file format that directs the `cide build` execution
+
+DESCRIPTION
+-----------
+
+The `cide.yml` file is encoded in the [YAML markup language](http://yaml.org/)
+and describes mostly how the Dockerfile will be generated.
+
+It has the following semantic:
+
+Root document
+-------------
+
+```yaml
+---
+# Image to base the build on
+#
+# required
+# type: string
+from: 'ubuntu'
+
+# A step executed as root. See the Step definition.
+as_root: {}
+
+# If set to true, inject the invoker's SSH key into the image.
+# This is used for shared github access for example.
+#
+# type: boolean
+use_ssh: no
+
+# A step executed as the "cide" user. See the Step definition.
+before: {}
+
+# Environment variables set at runtime. See the ENV definition.
+env: {}
+
+# Selects a file or directory to export. When set and cide is invoked with
+# --export the same directory will be copied back into the project's root.
+#
+# type: string
+export_dir:
+
+# When defined, executes and attaches the defined linked containers to the
+# CI runtime. See the Link definition.
+links: []
+
+# Determines what script to run to execute the tests. This is the main command
+# that is used to run the CI.
+#
+# The script has to exit with an exit-status of zero to succeed.
+#
+# default: "script/ci"
+# type: string
+run: rake
+```
+
+Step definition
+---------------
+
+Here is the format for a step.
+
+```yaml
+# An array or hash of files to add
+#
+# In the hash form, the target is on the left-hand side and source on the
+# right-hand side. If multiple values are passed on to the right then they are
+# all added to the same folder.
+#
+# If a URL is provided in the source it is fetched during the build.
+#
+# Note that source files should either come from a URL or from a file within
+# the project's directory.
+add:
+  /etc/cacert.pem: http://curl.se/cacert.pem
+  /src:
+    - Gemfile
+    - Gemfile.lock
+# or
+add:
+  - one
+  - two
+
+# Sets environment variables in this step (and next ones). See the ENV
+# definition.
+env: {}
+
+# A list of commands to run in that stage
+#
+# type: string or array of string
+run:
+  - bundle exec
+  - npm install
+# or
+run: go get ./...
+```
+
+If the step is defined as a string or array, those are interpreted as commands
+to add to that step.
+
+ENV definition
+--------------
+
+An array or hash of environment variables to load
+
+In the hash for, the left-hand side is the key and the right-hand side the
+value.
+
+If a hash value is nil or the array form is used, the environment variables
+are loaded from the cide invoker environment.
+
+```yaml
+env:
+  HOME: /cide
+  AWS_ACCESS_KEY_ID:
+# or
+env:
+  - AWS_ACCESS_SECRET_KEY
+```
+
+Link definition
+---------------
+
+A hash that describes a linked containers. Linked containers are automatically
+started before executing the main command and destroyed after that.
+
+```yaml
+# Gives a name to the container to execute. This also determines the hostname
+# the main container will be able to address this container with.
+#
+# If the name is missing, the name is extracted from the `from` key. For
+# example if the `from` value is "foobar/redis:2.6" the name will be "redis"
+#
+# type: string
+name: 'mysql'
+
+# Name of the image to pull and base the container on.
+#
+# type: string
+name: 'redis:2.6'
+
+# Environment variables for that container. See the ENV definition.
+env: {}
+
+# Single command to execute the container with.
+#
+# type: string
+run: 'redis-server'
+```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cide
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - zimbatm
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-02 00:00:00.000000000 Z
+date: 2015-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +53,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: md2man
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,8 +109,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |
-  cide makes it easy to reproduce CI builds on the developer computer by
-  providing the same docker environment.
+  cide is a command-line tool that runs tests in an isolated (docker)
+  environment. It allows to run the same command on the developer and CI
+  machines.
 email:
 - zimbatm@zimbatm.com
 executables:
@@ -104,22 +119,25 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".cide.yml"
 - ".editorconfig"
 - ".gitignore"
+- ".nojekyll"
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
-- LICENSE
+- LICENSE.md
 - README.md
 - Rakefile
 - bin/cide
 - cide
 - cide.gemspec
-- lib/cide.rb
+- cide.yml
+- docs/cide.yml.md
+- docs/sidebar.md
+- index.html
 - lib/cide/build.rb
 - lib/cide/build/config.rb
 - lib/cide/build/config_loader.rb
@@ -128,6 +146,12 @@ files:
 - lib/cide/default_cide.yml
 - lib/cide/docker.rb
 - lib/cide/dockerfile_template.erb
+- man/cide-build.1.md
+- man/cide-clean.1.md
+- man/cide-debug.1.md
+- man/cide-init.1.md
+- man/cide.1.md
+- man/cide.yml.1.md
 - spec/build_config_loader_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/zimbatm/cide
@@ -150,10 +174,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.7
 signing_key: 
 specification_version: 4
-summary: CI docker runner
+summary: Isolated test runner with Docker
 test_files:
 - spec/build_config_loader_spec.rb
 - spec/spec_helper.rb

data/lib/cide.rb

@@ -1,7 +0,0 @@
-# CIDE is a Continuous Integration Docker Environment runner
-#
-# The juicy bits are defined in CIDE::CLI
-module CIDE
-end
-
-require 'cide/cli'