deploy_doc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ad636b7c3d04d48cb1348f0a4a51144855b15e6c
+  data.tar.gz: 3e2d63ba1d5507ce621a87693ee2316908dfba93
+SHA512:
+  metadata.gz: 31ddd23250904ebfed56bce18dc65402115ddcc7a0be2cc310e3bf30b9cb733797c47ff17ba243d59f0c7070bcb25754d6539641ddae684edccba085d96ba218
+  data.tar.gz: 912167c2b23c5d4fc57c557ec7f229e125c26fdff5a7d5bf50a43f97e96b33ff6bf1436b24aa603141941b6849f8489c03f17e6555d7bd7464f8ef66c8d8beac

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.12.5

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at maarten@moretea.nl. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in deploy_doc.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Maarten Hoogendoorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,188 @@
+# DeployDoc
+
+## Synopsis
+With DeployDoc, you can test the deployment of your microservice constellation to multiple
+platforms, based on your end user documentation.
+Usually, a project will have documented the required steps to deploy the microservices.
+This documentation typically consists of a text with these steps embedded in it.
+We realized that by adding some annotations, these steps could be parsed by a computer and
+run in a CI pipeline. See the [syntax](#syntax) section below for more information about
+how to write these Markdown files.
+
+## Architecture
+- As a user, you must provide a **Markdown file** that contains the steps to set up the
+  infrastructure your app requires, deploy the app to this infrastructure, and finally destroy the
+  created infrastructure.
+- Optionally, you can provide an alternative **Docker Image**. It defaults to the `ruby` image.
+- The **`deploy_doc`** tool parses, extracts and converts the Markdown file into a JSON file which
+  contains all the steps that need to be run. (See the [syntax](#syntax) section below on
+  how to write these Markdown files).
+- The `deploy_doc` tool creates a docker container, and mounts (a) the JSON file containing the
+  steps that need to be run, (b) the runner script that interprets the JSON file and (c) the
+  data dir to `/deploy_doc/data`. The runner returns an appropriate status code to communicate
+  the result of the test run to the CI environment (see the [usage](#usage) section below).
+- Based on the value of the test output, the CI environment can generate and publish the
+  human readable and verified version version of the documentation.
+
+
+<img src="doc/fig/architecture.png">
+
+## Usage
+Install the `deploy_doc` gem, see the [installation instructions](#installation) below.
+
+```
+USAGE: deploy_doc <markdown_file> [options]
+    -h, --help                       Print help
+    -r, --run-test                   Run tests
+    -j, --dump-json                  Just parse the Markdown file and dump the steps to JSON
+    -c, --shell-in-container         Start a (temporary) docker container with the same environment as the tests will run in
+    -i, --docker-image=IMG_NAME      Use this docker image instead of the default 'ruby:2.3'
+    -d, --data-dir=DIR               Set the data directory, instead of the default '.'
+
+EXIT STATUS:
+  If all test passed, and the infrastructure has been cleaned up, 0 is returned.
+  If something went wrong, but there the infrastructure has been destroyed correctly,
+  a 1 error status is returned, but if the destruction of the infrastructure did not complete,
+  the process returns an error status 2. These cases will probably require manual cleanup steps.
+  Finally, a error status 3 is returned if the program is aborted. We cannot give any guarantees in this case!
+```
+
+NOTE: If you use a custom docker image, be sure that it contains a Ruby implementation with version >= 2.1
+
+## Phases in a DeployDoc
+The test runner has four phases:
+
+- `pre-install`, in which required additional software should be installed, such as Terraform.
+  If this phase fails, the tests just aborts, without attempting to destroy the infrastructure.
+  *NOTE*: This implies that it is very important to also install any the tool that is required
+  to tear down the infrastructure.
+- `create-infrastructure`, in which the cloud resources are created. If this phase fails,
+  the tests are skipped, but the `destroy-infrastructure` phase is executed.
+- `run-tests`, which should contain instructions that validate that the infrastructure is up and
+   running and that the microservices are deployed correctly.
+-  `destroy-infrastructure`, which must tear down the infrastructure.
+
+### Secrets phase
+There is an additional `require-env` phase, that can be used to pass in environmental variables to
+the steps. If they are not present, testing the documentation will result in an error message that
+these variables are not present.
+
+
+## Syntax
+The expected syntax is compatible with Jekyll.
+We expect the Markdown file to start with a YAML section, enclosed in a `---` delimiter.
+
+### Defining phases and steps
+Multiple shell snippets (steps) can be added to a phase.
+The phases are run in the order give in the previous section, after which each snippet is executed
+in the order of declaration in the file.
+
+The following syntaxes are supported to add snippets:
+
+ 1. Single line annotation, not visible in Markdown output
+
+        <!-- deploy-doc PHASE [VALUE]* -->
+
+ 2. Hidden multi-line annotation
+
+        <!-- deploy-doc-start PHASE [VALUE]*
+        CONTENT
+        -->
+
+ 3. Visible multi-line annotation
+
+        <!-- deploy-doc-start PHASE [VALUE]* -->
+        CONTENT
+        <!-- deploy-doc-end -->
+
+Note that due to current technical limitations of the test runner, each step is executed in a
+separate shell.  This implies that *setting* an environmental variable in one step, will not be
+available in a next step. A work-around is to load/store this information in files.
+The externally required environmental variables to store secrets are available in all steps.
+
+
+### Example DeployDoc
+
+```
+---
+deployDoc: true
+---
+# Hello World
+<!-- deploy-doc require-env ENV_A ENV_B -->
+
+<!-- deploy-doc-start pre-install -->
+
+    apt-get update
+    apt-get install -yq jq terraform
+
+<!-- deploy-doc-end -->
+
+<!-- deploy-doc-hidden pre-install
+
+  curl https://nixos.org/nix/install | sh
+  nix-env -i nixops
+
+-->
+
+<!-- deploy-doc-start create-infrastructure -->
+
+    # This both creates the infrastructure, and
+    # deploys a distributed application to it.
+    nixops create -d test_deployment ./deployment.nix
+    nixops deploy -d test_deployment
+
+<!-- deploy-doc-end -->
+
+<!-- deploy-doc-start run-tests -->
+
+    # Get the public endpoint
+    WEBAPP_HOST=`nixops export -d test_deployment | jq ' .[].resources["load-balancer"].publicIpv4' -r`
+
+    # Test that the webapp is up.
+    curl $WEBAPP_HOST
+
+<!-- deploy-doc-end -->
+
+<!-- deploy-doc-start destroy-infrastructure -->
+
+    nixops destroy -d test_deployment
+
+<!-- deploy-doc-end -->
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'deploy_doc'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install deploy_doc
+
+## Development of this gem
+
+After checking out the repo, run `bundle install` to install dependencies.
+Then, run `rake test` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push git commits and tags,
+and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/microservices-demo/deploy_doc.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "deploy_doc"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/deploy_doc.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'deploy_doc/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "deploy_doc"
+  spec.version       = DeployDoc::VERSION
+  spec.authors       = ["Maarten Hoogendoorn"]
+  spec.email         = ["maarten@moretea.nl"]
+
+  spec.summary       = %q{Test system for your deploment documentation for your application}
+  spec.description   = %q{Using DeployDoc's, you can make your documentation executable}
+  spec.homepage      = "https://github.com/microservices-demo/deploy_doc"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/doc/fig/architecture.dot

@@ -0,0 +1,69 @@
+digraph deploy_doc_architecture {
+  edge[minlen=1.8];
+  subgraph cluster_user_provided {
+    label= "User provided";
+    fontsize=10
+    node[shape="note"];
+    base_image[label="Docker Base Image"];
+    deploy_doc[label="documentation.md",fontname="mono"];
+  };
+
+  subgraph cluster_doc {
+    label="E.g. Yekyll";
+    labeljust="r";
+    fontsize=10;
+
+    generate_doc[label="Generate\ndocumentation"];
+  }
+
+
+  subgraph cluster_deploydoc {
+    label = "DeployDoc";
+    labeljust="l";
+    fontsize=10
+    script_generator[label="deploy_doc",fontname="mono"];
+    generated_script[label="Test steps\n(JSON file)", shape=note];
+  }
+
+  subgraph cluster_container{
+    label="Within container";
+    labeljust="l";
+    fontsize=10;
+
+    run_kubectl[label="Deploy to k8s\nwith kubectl"];
+    run_terraform[label="Terraform\ninfrastructure"];
+    run_test_script[shape="circle", label="Run tests"]
+    run_test_script -> run_tests[dir=both];
+    run_test_script -> run_terraform [dir=both];
+    run_test_script -> run_kubectl[dir=both];
+
+    run_tests[label="Run sanity\ntests"];
+  }
+
+
+  script_generator -> generated_script;
+  generated_script -> run_test_script;
+
+  deploy_doc -> script_generator;
+  base_image -> run_test_script;
+  deploy_doc -> generate_doc;
+
+  doc_output[shape="note",label="Documentation"];
+  subgraph cluster_outputs {
+    style=invis;
+    node[shape=note];
+    test_output[label="Test output"];
+
+    is_test_ok[shape="diamond", label="Test passed?"];
+    test_output->is_test_ok;
+    is_test_ok -> test_bad [label="No"];
+    is_test_ok -> publish_doc[label="yes"];
+    test_bad[shape="rect", label="Fail CI build"];
+    publish_doc[shape="default", label="Publish correct docs"];
+  }
+
+  doc_output -> publish_doc;
+
+  run_test_script -> test_output;
+  generate_doc -> doc_output;
+}

data/exe/deploy_doc

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "deploy_doc"
+require "deploy_doc/cli"
+
+require "optparse"
+DeployDoc::CLI.run!(ARGV)

data/lib/deploy_doc/cli.rb

@@ -0,0 +1,109 @@
+module DeployDoc
+  module CLI
+    def self.run!(arguments)
+      configuration = parse_arguments(arguments)
+
+      test_plan = TestPlan.from_file(configuration.markdown_file)
+
+      case configuration.action
+        when :run then self.do_run(test_plan, configuration)
+        when :dump_json then self.dump_json(test_plan, configuration)
+        when :just_docker_env then self.just_docker_env(test_plan, configuration)
+        else raise RuntimeError.new("No such action '#{configuration.action}'")
+      end
+    rescue DeployDoc::Error => e
+      puts "Runtime error: #{e.message}"
+      exit 1
+    end
+
+    def self.parse_arguments(arguments)
+      configuration = Config.defaults
+
+      opt_parser = OptionParser.new do |opts|
+        opts.banner = "USAGE: deploy_doc <markdown_file> [options]"
+
+        opts.on("-h", "--help", "Print help") do
+          puts opts
+          puts
+          puts "EXIT STATUS:"
+          puts "  If all test passed, and the infrastructure has been cleaned up, 0 is returned."
+          puts "  If something went wrong, but there the infrastructure has been destroyed correctly,"
+          puts "  a 1 error status is returned, but if the destruction of the infrastructure did not complete,"
+          puts "  the process returns an error status 2. These cases will probably require manual cleanup steps."
+          puts "  Finally, a error status 3 is returned if the program is aborted. We cannot give any guarrantees in this case!"
+          exit
+        end
+
+        opts.on("-r", "--run-test", "Run tests") do
+          configuration.action = :run
+        end
+
+        opts.on("-j", "--dump-json", "Just parse the Markdown file and dump the steps to JSON") do
+          configuration.action = :dump_json
+        end
+
+        opts.on("-c", "--shell-in-container", "Start a (temporary) docker container with the same environment as the tests will run in") do
+          configuration.action = :just_docker_env
+        end
+
+        opts.on("-iIMG_NAME", "--docker-image=IMG_NAME", "Use this docker image instead of the default '#{configuration.docker_image}'") do |image|
+          configuration.docker_image = image
+        end
+
+        opts.on("-dDIR", "--data-dir=DIR", "Set the data directory, instead of the default '#{configuration.data_dir}'")do |data_dir|
+          configuration.data_dir = data_dir
+        end
+      end
+      opt_parser.parse!(arguments)
+      configuration.markdown_file = arguments.shift
+
+      if configuration.markdown_file.nil?
+        raise DeployDoc::Error.new("No markdown file provided! Run `deploy_doc -h' to learn more about how to use this tool.")
+      end
+
+      if configuration.action.nil?
+        raise DeployDoc::Error.new("No action given. Either --run-tests, --dump-json or --shell-in-container must be specified")
+      end
+
+      configuration
+    end
+
+    def self.do_run(test_plan, configuration)
+      status = nil
+
+      test_instructions_file = Tempfile.new("deploydoc", "/tmp")
+      test_instructions_file.write test_plan.to_json
+      test_instructions_file.close
+      runner_path = File.expand_path("../../../runner/runner.rb", __FILE__)
+      extra_opts = [
+        "-v#{test_instructions_file.path}:/deploy_doc/steps.json",
+        "-v#{runner_path}:/deploy_doc/runner",
+      ]
+      system Docker.cmd(configuration, check_and_find_envs(test_plan), "ruby /deploy_doc/runner /deploy_doc/steps.json", extra_opts)
+      status = $?
+      test_instructions_file.close
+      test_instructions_file.unlink
+      exit status.exitstatus
+    end
+
+    def self.dump_json(test_plan, configuration)
+      puts test_plan.to_json
+    end
+
+    def self.just_docker_env(test_plan, configuration)
+      Kernel.exec Docker.cmd(configuration, check_and_find_envs(test_plan), "sh", ["-ti"])
+    end
+
+    def self.check_and_find_envs(test_plan)
+      test_plan.required_env_vars.map do |name|
+        val = ENV[name]
+        if val.nil?
+          $stderr.puts "Required environmental variable #{name} is not set"
+          exit 1
+        else
+          "-e#{name}=#{val}"
+        end
+      end.join(" ")
+    end
+  end
+end

data/lib/deploy_doc/config.rb

@@ -0,0 +1,7 @@
+module DeployDoc
+  class Config < Struct.new(:action, :markdown_file, :docker_socket, :docker_image, :data_dir)
+    def self.defaults
+      Config.new(nil, nil, "unix:///var/run/docker.sock", "ruby:2.3", ".")
+    end
+  end
+end

data/lib/deploy_doc/docker.rb

@@ -0,0 +1,36 @@
+module DeployDoc
+  module Docker
+    def self.cmd(configuration, envs, cmd, extra_opts = [])
+      data_dir = if configuration.data_dir == "."
+                   Dir.pwd
+                 else
+                   configuration.data_dir
+                 end
+
+      docker_cmd = [
+        "docker", 
+        "run", 
+        "-it",
+        "--rm", 
+        envs, 
+        "-v#{data_dir}:/deploy_doc/data/",
+        "-w/deploy_doc/data/"
+      ]
+
+      # Expose the host host docker daemon in the child docker container.
+      docker_socket_protocol, docker_socket_address = configuration.docker_socket.split("://",2)
+      case docker_socket_protocol
+      when "unix"
+        docker_cmd.push "-v#{docker_socket_address}:/var/run/docker.sock"
+      when "tcp"
+        docker_cmd.push "-e DOCKER_HOST='#{configuration.docker_socket}'"
+      else
+        raise DeployDocError.new("Unkown docker socket protocol '#{docker_socket_protocol}'")
+      end
+
+      docker_cmd += extra_opts
+      docker_cmd += [configuration.docker_image, cmd]
+      docker_cmd.join(" ")
+    end
+  end
+end

data/lib/deploy_doc/error.rb

@@ -0,0 +1,4 @@
+module DeployDoc
+  class Error < RuntimeError
+  end
+end

data/lib/deploy_doc/test_plan/annotator_parser.rb

@@ -0,0 +1,120 @@
+module DeployDoc
+  class TestPlan
+    class AnnotationParser
+      Annotation = Struct.new(:source_name, :line_span, :kind, :params, :content)
+
+      def self.parse(markdown, path="<unknown>")
+        AnnotationParser.new(markdown, path).parse!
+      end
+
+      def initialize(markdown, source_name="<unknown>")
+        @source_name = source_name
+        @markdown_lines = markdown.split("\n")
+      end
+
+      def parse!
+        @annotations = []
+        @parse_idx = 0
+
+        while !eof_reached?
+          parse_block || parse_inline || parse_single_line || parse_text
+        end
+
+        @annotations
+      end
+
+      private
+
+      def parse_text
+        inc_line # ignore text, line by line
+      end
+
+      BLOCK_START  = /^<!-- deploy-doc-start (?<kind>[-\w]+)( )?(?<params>.*) -->/
+      BLOCK_END    = /^<!-- deploy-doc-end -->/
+
+      INLINE_START = /^<!-- deploy-doc-hidden (?<kind>[-\w]+)( )?(?<params>.*)/
+      INLINE_END   = /^-->/
+
+      SINGLE_LINE  = /^<!-- deploy-doc (?<kind>[-\w]+)( )?(?<params>.*) -->/
+
+      def parse_block
+        if (match = BLOCK_START.match(current_line)).nil?
+          false
+        else
+          inc_line
+          start_line = current_line_nr
+          kind = match["kind"]
+          params = match["params"].split(/\s+/)
+          content = ""
+          loop do
+            if eof_reached?
+              raise("Unexpected end of file; --> not closed? started on #{@source_name}:#{start_line}")
+            elsif !(BLOCK_END.match(current_line).nil?)
+              end_line = current_line_nr() -1
+              @annotations << Annotation.new(@source_name, [start_line, end_line], kind, params, content)
+              return true
+            else
+              content += current_line + "\n"
+            end
+            inc_line
+          end
+          true
+        end
+      end
+
+      def parse_inline
+        if (match = INLINE_START.match(current_line)).nil?
+          false
+        else
+          inc_line
+          start_line = current_line_nr
+          kind = match["kind"]
+          params = match["params"].split(/\s+/)
+          content = ""
+          loop do
+            if eof_reached?
+              raise("Unexpected end of file; --> not closed? started on #{@source_name}:#{start_line}")
+            elsif !(INLINE_END.match(current_line).nil?)
+              end_line = current_line_nr() -1
+              @annotations << Annotation.new(@source_name, [start_line, end_line], kind, params, content)
+              return true
+            else
+              content += current_line + "\n"
+            end
+            inc_line
+          end
+          true
+        end
+      end
+
+      def parse_single_line
+        if (match = SINGLE_LINE.match(current_line)).nil?
+          false
+        else
+          kind = match["kind"]
+          params = match["params"].split(/\s+/)
+          @annotations << Annotation.new(@source_name, [current_line_nr, current_line_nr], kind, params, nil)
+          inc_line
+        end
+      end
+
+      ##### Helper functions ####
+
+      def eof_reached?
+        @parse_idx >= @markdown_lines.length
+      end
+
+      def current_line
+        @markdown_lines[@parse_idx]
+      end
+
+      def current_line_nr
+        @parse_idx + 1
+      end
+
+      def inc_line
+        @parse_idx+=1
+      end
+    end
+  end
+end

data/lib/deploy_doc/test_plan.rb

@@ -0,0 +1,99 @@
+module DeployDoc
+  class TestPlan
+    require_relative "test_plan/annotator_parser"
+
+    PHASES = ["pre-install", "create-infrastructure", "run-tests", "destroy-infrastructure"]
+
+    class Step < Struct.new(:source_name, :line_span, :shell)
+      def full_name
+        "#{source_name}:#{line_span.inspect}"
+      end
+    end
+
+    def self.from_file(file_name)
+      content = File.read(file_name)
+      self.from_str(content, file_name)
+    end
+
+    def self.from_str(content, file_name="<unknown file>")
+      metadata = self.parse_metadata(content, file_name)
+
+      if metadata["deployDoc"] != true
+        raise DeployDoc::Error.new("Markdown file #{file_name} does not have a 'deployDoc:true' metadatum")
+      end
+
+      annotations = AnnotationParser.parse(content, file_name)
+      required_env_vars = (annotations.select { |a| a.kind == "require-env" }).map { |a| a.params }.flatten
+      phases = self.phases_from_annotations(annotations)
+      TestPlan.new(metadata, required_env_vars, phases)
+    end
+
+    def self.parse_metadata(content, file_name)
+      metadata = content.split("---",3)[1]
+      YAML.load(metadata)
+    rescue
+      raise Error.new("Could not parse metadata in #{file_name}")
+    end
+
+    def self.phases_from_annotations(annotations)
+      phases = {}
+
+      PHASES.each do |phase|
+        phases[phase] = (annotations.select { |a| a.kind == phase }).map { |a| Step.new(a.source_name, a.line_span, a.content) }
+      end
+
+      phases
+    end
+
+    attr_reader :metadata
+    attr_reader :required_env_vars
+    attr_reader :steps_in_phases
+
+    def initialize(metadata, required_env_vars, steps_in_phases)
+      @metadata = metadata
+      @required_env_vars = required_env_vars
+      @steps_in_phases = steps_in_phases
+    end
+
+    def to_s
+     parts = []
+     parts << "Deployment test plan:"
+     parts << ""
+     parts << "Required environment parameters"
+
+     @required_env_vars.each do |e|
+       parts << "  - #{e}"
+     end
+
+     PHASES.each do |phase|
+       parts << "Steps in phase #{phase}:"
+       @steps_in_phases[phase].each do |step|
+         parts << "- #{step.source_name}:#{step.line_span.inspect}"
+         parts << step.shell
+       end
+     end
+
+     parts.join("\n")
+    end
+
+    def missing_env_vars
+      @required_env_vars.select { |e| ENV[e].nil? }
+    end
+
+    def to_json
+      json = {}
+
+      PHASES.each do |phase_name|
+        json[phase_name] = []
+        @steps_in_phases[phase_name].each do |step|
+          json[phase_name].push({
+            line_span: step.line_span.inspect, 
+            shell: step.shell.strip
+          })
+        end
+      end
+
+      JSON.pretty_generate(json)
+    end
+  end
+end

data/lib/deploy_doc/version.rb

@@ -0,0 +1,3 @@
+module DeployDoc
+  VERSION = "0.1.0"
+end

data/lib/deploy_doc.rb

@@ -0,0 +1,13 @@
+require "yaml"
+require "json"
+require "tempfile"
+
+require "deploy_doc/version"
+require "deploy_doc/error"
+require "deploy_doc/config"
+require "deploy_doc/docker"
+require "deploy_doc/test_plan"
+
+
+module DeployDoc
+end

data/runner/runner.rb

@@ -0,0 +1,143 @@
+require 'json'
+require 'open3'
+$stdout.sync = true
+$stderr.sync = true
+
+class StepFailed < RuntimeError
+  def initialize(phase, location)
+    super("on lines #{location} in phase #{phase}")
+  end
+end
+
+all_steps = JSON.load(File.read(ARGV.first))
+
+def report_error(e)
+  puts
+  puts red { "#{e.class}: #{e}" }
+  puts
+  $all_passed = false
+end
+
+def run_phase(all_steps, name)
+  puts(bold { underline { name}})
+  steps = all_steps[name]
+  if steps.empty?
+    puts yellow { '  - No steps in this phase'}
+  else
+    steps.each do |step|
+      puts blue { "  + Running step #{step["line_span"]}" }
+
+      shellcode = "set +e\n" + step["shell"]
+      begin
+        Open3.popen2e(shellcode) do |stdin, stdout_stderr, wait_exit_code_of_child|
+          $current_io_thread = wait_exit_code_of_child
+          buffer = ""
+
+          loop do
+            begin
+              read = stdout_stderr.read_nonblock(1024)
+            rescue IO::EAGAINWaitReadable
+              IO.select([stdout_stderr])
+              retry
+            rescue EOFError
+              if buffer.length > 0
+                lines = buffer.split("\n")
+                lines.each do |line|
+                  print_line(line)
+                end
+              end
+              break
+            end
+            buffer += read
+            line, new_buffer = buffer.split("\n", 2)
+            if new_buffer != nil
+              print_line(line)
+              buffer = new_buffer
+            end
+          end
+
+          if wait_exit_code_of_child.value != 0
+            raise StepFailed.new(name, step["line_span"])
+          end
+        end
+      ensure
+        $current_io_thread = nil
+      end
+    end
+  end
+ensure
+  puts
+end
+
+def print_line(line)
+  puts((blue { "  | "}) + line)
+end
+
+def bold
+  "\033[1m" + yield + "\033[0m"
+end
+
+def underline
+  "\033[4m" + yield + "\033[0m"
+end
+
+def red
+  "\033[31m" + yield + "\033[0m"
+end
+
+def yellow
+  "\033[33m" + yield + "\033[0m"
+end
+
+def blue
+  "\033[34m" + yield + "\033[0m"
+end
+
+begin
+  begin
+    run_phase(all_steps, "pre-install")
+  rescue StepFailed => e
+    report_error(e)
+    exit 1
+  end
+
+  all_passed = true
+  begin
+    begin
+      run_phase(all_steps, "create-infrastructure")
+      run_phase(all_steps, "run-tests")
+    rescue Exception => e
+      report_error(e)
+      puts "Skipping next steps, jump to cleaning up\n"
+      all_passed = false
+    end
+
+    begin
+      run_phase(all_steps, "destroy-infrastructure")
+    rescue Exception => e
+      report_error(e)
+      puts "    " + bold { red { "#" * 46 } }
+      puts "    " + bold { red { "#   " } } + bold { red { underline { "Failed to clean up the infrastructure!" } } } + bold { red { "   #"}}
+      puts "    " + bold { red { "#" * 46 } }
+      exit 2
+    end
+  end
+
+  if all_passed
+    exit 0
+  else
+    exit 1
+  end
+rescue Interrupt
+  puts bold { red { "Interrupted!" } }
+  if $current_io_thread
+    puts "Killing child process #{$current_io_thread.pid}"
+    begin
+     Process.kill("KILL",$current_io_thread.pid)
+    rescue
+      # Don't care if the PID doesn't exist anymore.
+      # All bets are off in any case.
+    end
+  end
+  exit 3
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: deploy_doc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maarten Hoogendoorn
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Using DeployDoc's, you can make your documentation executable
+email:
+- maarten@moretea.nl
+executables:
+- deploy_doc
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- deploy_doc.gemspec
+- doc/fig/architecture.dot
+- doc/fig/architecture.png
+- exe/deploy_doc
+- lib/deploy_doc.rb
+- lib/deploy_doc/cli.rb
+- lib/deploy_doc/config.rb
+- lib/deploy_doc/docker.rb
+- lib/deploy_doc/error.rb
+- lib/deploy_doc/test_plan.rb
+- lib/deploy_doc/test_plan/annotator_parser.rb
+- lib/deploy_doc/version.rb
+- runner/runner.rb
+homepage: https://github.com/microservices-demo/deploy_doc
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Test system for your deploment documentation for your application
+test_files: []