--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Thu Feb 09 09:47:04 2017 -0800
@@ -0,0 +1,200 @@
+# Speedtest
+
+## The Pattern
+
+`speedtest`
+will use this pattern for outer loop testing:
+
+- a [Docker](http://docker.io/) container is created from a
+  `speedtest` script,
+  and a docker
+  [CMD]
+  (https://docs.docker.com/v1.8/reference/builder/#cmd)
+  that will run
+  the appropriate test and post a JSON blob to an
+  [Elasticsearch](https://www.elastic.co/) node
+
+- the Docker container is dispatched to a container service
+  such that it may be run at
+  cloud scale and from a variety of regions
+
+- the test [CMD]
+  (http://docs.docker.com/engine/reference/builder/#cmd)
+  of the container contains steps that will generate
+  JSON data and post this to an Elasticsearch node.  This
+  Elasticsearch data may then be analyzed and utilized for reporting
+  of system status.
+
+This pattern is of general utility for blackbox testing and monitoring
+of a web system under test. Monitoring may be performed in a continuous
+and ongoing basis, the Elasticsearch data combed for performance information.
+
+
+## Installation
+
+`speedtest` follows fairly standard
+[python packaging]
+(https://python-packaging-user-guide.readthedocs.org/en/latest/)
+practices.  We do need other software, like
+[docker](http://docker.io), to help us along.
+
+Let's get started!
+
+
+## What Speedtest Gives You
+
+`speedtest` attempts to provide a suite of tools for making worldwide
+dockerized speedtests a reality.  Many of these are provide in terms
+of [setuptools](https://pythonhosted.org/setuptools/)
+[entry points]
+(https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins),
+including
+[console scripts]
+(https://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation).
+
+Several console scripts are also installed with `speedtest`.
+All provided console scripts utilize
+[argparse](https://docs.python.org/2/library/argparse.html)
+for their command line interface.  Detailed usage information for a
+script may be obtained by using the `--help` command line switch.
+For example: `speedtest --help` .
+
+
+## About Speedtest
+
+`speedtest` is a collection of scripts and utilities to make real the
+pattern of docker container dispatch for data
+gathering via JSON output to Elasticsearch.
+
+While `Dockerfile`s are a good abstraction layer for building
+[linux containers]
+(https://en.wikipedia.org/wiki/LXC),
+often the run steps must be automated and parameterized.
+
+##  speedtest with local results
+
+Usage information is available with the `--help` flag:
+
+    speedtest --help
+
+Arbitrary metadata may be added with the `--variables` flag.  While the results processing and information available should be refined, right now we are erring on the side of too much, which is at least fairly flexible.
+
+To run a speedtest versus the URL http://k0s.org/playground/1M.bin adding the variable `foo` with value of `bar` with local JSON results measuring every 100k, do:
+
+    speedtest --variables foo=bar --format json --chunk $((100*1024)) http://k0s.org/playground/1M.bin
+
+
+## Containers
+
+### Containerized Download Speed Testing
+
+`speedtest.py`
+
+(and, equivalently, the `speedtest` [console script]
+(http://python-packaging.readthedocs.org/en/latest/command-line-scripts.html#the-console-scripts-entry-point))
+measures download speed over time given a URL:
+
+    # speedtest http://k0s.org/playground/1M.bin
+    ...
+    {"duration": 1.7867929935455322, "cumulative": 586848, "speed": 209367, "size": 1048576}
+
+
+### Containerized Dispatching
+
+- pull the Docker image from a container registry
+- run the Docker image
+
+### Container Registry
+
+In order to make use of containerized dispatch, you may want a
+[docker registry](https://docs.docker.com/registry/):
+
+- https://docs.docker.com/registry/deploying/
+- https://www.docker.com/docker-trusted-registry
+- https://github.com/docker/distribution
+- https://www.docker.com/aws
+
+[Docker hub](https://hub.docker.com/)
+has an official [Docker](https://www.docker.com)
+repository for a
+[Docker registry]
+(https://hub.docker.com/_/registry/).  How meta is that?  You can get
+started just by running:
+
+    docker run registry:2
+
+
+## Elasticsearch
+
+_"Elasticsearch is a search server based on Lucene. It provides a
+distributed, multitenant-capable full-text search engine with a HTTP
+web interface and schema-free JSON documents. Elasticsearch is
+developed in Java and is released as open source under the terms of
+the Apache License."_,
+[Wikipedia](https://en.wikipedia.org/wiki/Elasticsearch)
+
+The schema-free data store together with the easy RESTful interface
+make [Elasticsearch]
+(https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
+a great place for `speedtest` to put its results.
+
+There is a docker container for Elasticsearch available:
+https://hub.docker.com/_/elasticsearch/
+
+The results of `speedtest` may be posted to Elasticsearch:
+
+    # curl -XPOST localhost:9200/speedtest/results?pretty -d "$(speedtest http://k0s.org/playground/1M.bin | tail -n 1)"
+    {
+      "_index" : "speedtest",
+      "_type" : "results",
+      "_id" : "AVGNmWMTVkaacKUEikLl",
+      "_version" : 1,
+      "_shards" : {
+        "total" : 2,
+        "successful" : 1,
+        "failed" : 0
+      },
+      "created" : true
+    }
+
+However, for lots of data we probably want to use the
+[bulk API]
+(https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html)
+
+    # speedtest 'http://k0s.org/playground/1M.bin' --fmt elasticsearch --chunk $((1024*1024)) -o 'http://1.2.3.4:32793/speedtest/results/_bulk'
+    {"took":1,"errors":false,"items":[{"create":{"_index":"speedtest","_type":"results","_id":"AVVU7PIeZtDhCquHQrZV","_version":1,"status":201}}]}
+
+Note that the index and type *must* be specified in the output URL for this to work.
+See https://www.elastic.co/blog/index-vs-type for clarification of why this is a
+good thing.
+
+
+JSON blobs are uploaded to an Elasticsearch instance.
+
+
+## Links
+
+     ,           ,
+     |`-._   _.-'|
+     \    `-'    /
+      `-._   _.-'
+          `#'
+     ~~~~~~~~~~~~~
+
+[Docker](http://docker.com/):
+
+- https://docs.docker.com/machine/get-started/
+- https://github.com/victorlin/crane
+- https://docker-py.readthedocs.org/en/latest/
+
+
+Elasticsearch:
+- [The Definitive Guide](https://www.elastic.co/guide/en/elasticsearch/guide/index.html)
+- https://www.elastic.co/guide/en/elasticsearch/reference/current/_modifying_your_data.html
+- https://hub.docker.com/_/elasticsearch/
+- [Python Elasticsearch Client]
+  (http://elasticsearch-py.readthedocs.org/en/master/index.html)
+- https://bitquabit.com/post/having-fun-python-and-elasticsearch-part-1/
+
+
+[Jeff Hammel](https://hub.docker.com/u/jehammel/)