Merge Nulecule specification into Atomic App

This commit merges the documentation located at
github.com/projectatomic/nulecule into Atomic App.

The changes included with the merge are:
* Remove reference to developer tooling being added
* Remove reference to example folder, now directs
to nulecule-library
* Remove redundant information (links to #nulecule
irc channel) already present in root README.md
* Move .json spec files to json folder
* Clean up documentation links to link to the
correct directory
* Capitalize spec doc files, move them all to a
single folder
* Add link to NULECULE_FILE.md reference in main
spec README.md
* Add link to specification in the root README.md
* Update description of Nulecule in the main README.md

README.md

@@ -2,7 +2,7 @@
 
 ![](docs/images/logo.png "Project Atomic")
 
-Atomic App is a reference implementation of the [Nulecule](https://github.com/projectatomic/nulecule) specification. Packaged Atomic App containers are "Nuleculized" and each component of the package is a "Nulecule".
+Atomic App is a reference implementation of the [Nulecule](docs/spec/README.md) specification. Packaged Atomic App containers are "Nuleculized" and each component of the package is a "Nulecule".
 
 Atomic App is used to bootstrap packaged container environments and run them on multiple container orchestrators. It is designed from the ground-up to be portable and provider pluggable.
 
@@ -48,6 +48,7 @@ This README contains some high level overview information on Atomic App. The det
 7. [Specification coverage](docs/spec_coverage.md)
 8. [Contributing](CONTRIBUTING.md)
 9. [Dependencies](docs/requirements.md)
+10. [Specification](docs/spec/README.md)
 
 
 ## Getting started
@@ -89,6 +90,10 @@ If you have any issues or get stuck, feel free to open a GitHub issue or reach u
 
 See [REQUIREMENTS.md](docs/requirements.md) for a list of current Atomic App dependencies.
 
+## Specification
+
+Want to view the specification and contribute to changes? See the [Nulecule spec](docs/spec/README.MD) for more information.
+
 ## Communication channels
 
 * IRC: __#nulecule__ on irc.freenode.net

docs/spec/GETTING_STARTED.md

@@ -0,0 +1,90 @@
+# Getting Started with Nulecule
+
+You have an application you want to package up as a Nulecule for distribution. It's composed of one or more containers that together link to provide your application.
+
+## Plan
+1. Determine what components of your application are custom and which are "stock" parts.  For example, do you need a custom web server, or do you just need to load a specific configuration onto an already packaged web server.
+1. Find your resources. 
+    - **nulecule applications** Are there existing Nulecule Applications you can leverage in your own application?
+    - **container images** Carefully consider if you really need to build your own containers.  For example, do you really need your own web server or database image? If you're writing a Dockerfile for a common service, try to find a well-known, supported, certified, stable image that you can build on.
+    - **provider orchestration templates** When you are considering how to provide configuration for orchestration providers, such as kubernetes files (service, replication controller, pod) or OpenShift or Docker Compose files, see if you can use exising templates or known good files. As with container images, if you're writing files for common services, try to find well-known, supported, certified, stable templates that you can build on.
+
+## Prepare
+From the planning phase, you've got a collection of remote and local sources that your application will be comprised of.
+
+1. Start with the containers. Understand how they run standalone. Get them running.  Make sure the entire application runs manually.
+1. Orchestrate the containers on the target provider. Start simply and build up. For example, with kubernetes just deploy as a pod. Once that succeeds, add a service, and then some replication controllers. There are many opportunities for error -- so make small changes, test and iterate slowly. Verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently. Use a method that can be easily incorporated into your development workflow: small change -> save -> validate -> test -> rinse and repeat.
+1. Test both custom and stock services together. Nulecule won't do magical things. The pieces must all work together before they can be packaged up as a unit.
+
+## Package
+Only when everything is working are you ready to package the application. In this phase you'll be interacting with the [Nulecule specification](/spec).
+
+1. Download a [Nulecule template](/spec/examples/template) to start from.
+1. In the Nulecule file, create one or more lists of things under `graph`. These represent the different components that make up your application. Names are arbitrary. Remember to verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently.
+
+    1. If your sources are remote, then all that is needed is a name and source. Remote sources are other Nulecule applications.
+
+            graph:
+            - name: mydb
+              source: "docker://registry.example.com/some/database"
+    1. If your sources are local, then provide a name and an artifacts key that will reference the source file(s). Each provider will have a key specifying the provider. For example, "docker" or "kubernetes".
+
+            graph:
+            - name: myapp
+              artifacts:
+                kubernetes:
+                  - file:///artifacts/kubernetes/pod.json
+                  - file:///artifacts/kubernetes/service.json
+
+1. Put all of the provider files into a directory structure that corresponds to the provider artifacts section in the Nulecule file. Using the above example, `artifacts/kubernetes/<file>.json`. The structure should resemble something like this:
+
+        ├── Dockerfile
+        ├── artifacts
+        │   └── kubernetes
+        │       ├── pod.json
+        │       └── service.json
+        ├── Nulecule
+        └── README.md
+
+1. Consider the different ways your application may be deployed. There will likely be many parameters that need to be exposed at deployment. It's best to overdo this and provide defaults whenever possible. Go through the provider files and change any values. For example `database_pass: changeme` becomes `database_pass: $db_pass`. The name of the parameter is `db_pass`. These go into the params section of the Nulecule file under each provider. For example:
+
+
+        graph:
+        - mydb:
+          ...
+          params:
+          - name: db_pass
+            description: database passphrase
+          - name: port
+            description: frontend TCP port
+            default: 80
+
+1. Consider any additional information that is useful for deployment. Write a README file focused on deployment. Use a popular format such as Markdown or asciidoc so it can be read from a terminal window or rendered in a graphical interface.
+    * what does this application do?
+    * what provider environment(s) do I need to have setup before I deploy it?
+    * how do I verify that it has been deployed correctly?
+
+1. Add a metadata section, including a name, description and license information. Arbitrary metadata may also be added. Consider using keyword tags that may be useful for deployment management. For example:
+
+        metadata:
+          name: My Cool App
+          appversion: 1.0.0
+          description: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+          license:
+            name: GPLv3
+            url: http://www.example.com/license
+          tags:
+            - foo
+            - bar
+
+1. Before packaging up into a container, try running it in a test mode if one is provided by your Nulecule implementation.  If you are using the [Atomic App reference implementation](https://github.com/projectatomic/atomicapp), use the `dry-run` and `verbose` options as follows: `atomicapp --dry-run --verbose run`. This should output the commands that will run. Common errors:
+    * provider files don't match the artifact relative path
+    * yaml or json is not valid
+    * missing parameter
+
+1. Once the Nulecule file and provider artifacts are working, package the application as a container. Typically, this means basing it off of an executable image provided by the implementation of Nulecule you are using.  If you are using the [Atomic App reference implementation](https://github.com/projectatomic/atomicapp), the stock Dockerfile may be used, unaltered, unless you have a special use case.
+
+        [sudo] docker build -t mydb-app .
+
+## Push & Pull
+Push the image to a registry. Tell people about it and see if they can deploy your application without any assistance. If they have questions, you probably should enhance the application and parameter descriptions so they are clear.

docs/spec/GLOSSARY.md

@@ -0,0 +1,13 @@
+# Nulecule Glossary
+
+* __Container Image__ - Platform-agnostic term referring to Docker, Rkt or other packaging and transport protocol
+* __Layered Image__ - The foundation image of a container plus other tools, applications and content added
+* __Association__ of container images to the multi-container Nulecule application:
+  + __Aggregation__ of one or more discrete container images integral to the operation and coupled to the lifecycle of the Nulecule application - can be another Nulecule Application or container image reference
+  + __Composition__ refers to one or more container images that are required and tightly coupled to the Nulecule application - can be another Nulecule Application or container image reference
+* __Include__ - Refers to the ability to include common resources, parameters or definitions needed to deploy onto a orchestration provider. For example, an OpenShift provider may include the kubernetes provider artifacts and add OpenShift functionality on top of kubernetes capabilities.
+* __Provider__ - Plugin interface for specific deployment platform, an orchestration provider
+* __Dependency Management__ - Refers to the ability to define order of deployment and managed dependencies including configurable parameters layered on top of stock container images, as well as the providers included in the application definition
+* __Directed Graph__ - Declarative representation of dependencies in the context of a multi-container Nulecule application
+* __Parameters__ - Variables that can have default values and can be overridden by answerfile.conf
+

docs/spec/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,34 @@
+# Implementation Guide
+
+This specification has been fully described in the [schema.json](/spec/schema.json) file. Developer and deployment tools should be implemented using this file.
+
+## Developer Tools
+
+Developer tooling helps application developers or designers get going quickly. Tools may be template-based or wizard-style tools, command line or graphical interface. When creating a tool for developers decide how much assistance you want to expose for the providers. Each provider has its own documentation and potential tooling but integrating provider features can be a big help to getting something working quickly.
+
+Wizard-style tools that generate the files for an application require these fields for input:
+
+* name
+* description
+* version (application)
+
+Each "application" component the user wants to define will compose the "graph" for the Nulecule. A component may either be a remote application or defined locally in the directory structure.
+
+**Remote applications**
+
+Remote applications are other nulecule container images, for example `someuser/mariadb-app`. No other information is needed.
+
+**Local applications**
+
+Local applications are defined by a directory in the graph. These fields are required for input:
+
+* application name: this is added to the Nulecule graph and creates a directory in the graph.
+* provider: a subdirectory of the application directory
+
+**Providers**
+
+Provider files may be generated based on some templates. Providing a mechanism to parameterize these files helps the developer understand how parameterization works. For example, if a set of kubernetes template files are pulled in allowing the developer to parameterize some values in the pod file would update the pod file and create a `key = value` pair in the application section of the `params.conf` file. For required values without defaults set the value to `None` in `params.conf`. With this example as a starting point the developer can then easily manipulate parameters by manually editing the files based on the demonstrated pattern.
+
+## Runtime Tools
+
+The Reference implementation, Atomic App, coded in python is located at: https://github.com/projectatomic/atomicapp

docs/spec/LIFECYCLE.md

@@ -0,0 +1,54 @@
+# Lifecycle of the Specification
+
+This document and the processes it describes will become effective starting Nulecule Specification 0.0.2. It is valid until replaced by a newer version or noted otherwise.
+
+## Normative Document
+
+The normative Nulecule Specification document will be published at http://www.projectatomic.io/nulecule/spec/<major.minor.patch>/
+Versioning is using the [semantic versioning scheme](http://semver.org/spec/v2.0.0.html).
+
+In addition to the human readable HTML document, a JSON formated machine readable version of the specification will be published at the same URL path as the HTML document. The document name will be schema.json and may reference other files using the JSON DRAFT4 references.
+
+The normative machine readable Nulecule Specification document will be published at https://github.com/projectatomic/nulecule/blob/v<major.minor.patch>/spec/<major.minor.patch>/schema.json
+
+## States
+
+The Nulecule Specification will have a certain set of releases, we will use semantic versioning to identify the releases.
+Prior each release there will be a draft version of the release. This will be used to work/collaborate on the spec itself.
+
+## Contributors and release process
+
+Everybody is welcome to contribute to the draft version of the upcoming release. This will be documented by pull
+requests (to the github repository of the Nulecule Specification) to the draft of the specification. Once a draft
+has stabilized, it will be prepared by the specification maintainers and prepared for release. The maintainers
+will release a new release of the specification.
+
+### Changes to a Releases
+
+Changes to released versions of the specification will not change the structure or feature set of the specification.
+They are only meant to fix spelling or language errors, add or correct examples.
+
+Collaboration on the draft of the next release of the Nulecule Specification will be done on the master branch of the github
+repository of the Nulecule Specification. The release task itself is rather short: the maintainers will tag the repository
+and provide the human and machine readable versions of the normative documents.
+
+## Release tasks
+
+This chapter will walk you thru the steps to be taken to
+
+ * prepare a draft - so that the community can work on it
+ * release - so that a new version of the spec is created
+
+### prepare a draft
+
+Given the example that the current version of the spec is 0.5.0, collaboration of the specification will continue on the master branch
+of https://github.com/projectatomic/nulecule
+
+### release (move from draft to new version)
+
+This will bring the draft version of the spec to a released version of the spec: `git tag v0.6.0 -m 'v0.6.0'` After that, one of the maintainers will
+publish the human and machine readable files to http://projectatomic.io/nulecule/spec/0.6.0/
+
+## Maintainers
+
+Please see the MAINTAINERS file for a list of maintainers of the Nulecule Specification.