Merge pull request #25 from arschles/readme

doc(README.md): add basic documentation

Author: arschles

README.md

@@ -1,61 +1,14 @@
-# Prototype Component Repo
+# Deis Builder
 
-This repo is a prototype for what a Deis component's Git repository
-should look like.
+[![Build Status](https://travis-ci.org/deis/minio.svg?branch=master)](https://travis-ci.org/deis/minio) [![Go Report Card](http://goreportcard.com/badge/deis/builder)](http://goreportcard.com/report/deis/builder)
 
-A Deis component is...
+This repository holds the Deis Builder. Builder runs a git server to respond to `git push`es from clients. When it receives a push, it takes the following high level steps:
 
-- An isolated piece of functionality (e.g. a microservice)
-- That can be packaged into a container (via `docker build`)
-- And can be run inside of Kubernetes
-
-Typically, Deis components are written in Go.
-
-## Practical Usage
-
-If you want to experiment with creating a new repo using this framework,
-try something like this:
-
-```
-$ mkdir my_project
-$ cd my_project
-$ curl -fsSL https://github.com/technosophos/prototype-repo/archive/master.tar.gz | tar -zxv --strip-components 1
-```
-
-## First-Class Kubernetes
-
-Every component must define the appropriate Kubernetes files.
-Preferably, components should use *Replication Controllers* over pods,
-and use *Services* for autodiscovery.
-
-*Labels* should be used for versioning components and also for
-identifying components as part of Deis.
-
-*Secrets* should be used for storing small bits of shared information,
-and their contents may be set at startup time.
-
-All Kubernetes definitions should be placed in the `manifests/` directory.
-
-The _Makefile_ should have targets that use `kubectl` to load
-definitions into Kubernetes.
-
-## Dockerfiles are for Running
-
-Source code should be built either outside of Docker or in a special
-Docker build phase.
-
-A separate Dockerfile should be used for building the image. That
-Dockerfile should always be placed inside of the `rootfs` directory, and
-should manage the final image size appropriately.
-
-(See the Makefile for one possible way of doing a Docker build phase)
-
-## RootFS
-
-All files that are to be packaged into the container should be written
-to the `rootfs/` folder.
-
-## Extended Testing
-
-Along with unit tests, Deis values functional and integration testing.
-These tests should go in the `_tests` folder.
+1. Accepts the code and writes to the local file system
+2. Calls `git archive` to produce a tarball (i.e. a `.tar.gz` file) on the local file system
+3. Saves the tarball according to the following rules:
+  - If the `DEIS_MINIO_SERVICE_HOST` and `DEIS_MINIO_SERVICE_PORT` environment variables exist, uses the [`mc`](https://github.com/minio/mc) client to save to the [Minio](https://github.com/minio/minio) server at `http://$DEIS_MINIO_SERVICE_HOST:$DEIS_MINIO_SERVICE_HOST`
+  - Otherwise, if the `DEIS_OUTSIDE_STORAGE_HOST` and `DEIS_OUTSIDE_STORAGE_PORT` environment variables exist, uses the [`mc`](https://github.com/minio/mc) client to save to S3 server (or server that adheres to the S3 API) at `https://$DEIS_OUTSIDE_STORAGE_HOST:$DEIS_OUTSIDE_STORAGE_PORT` (this functionality is currently waiting for merge at https://github.com/deis/builder/pull/21).
+4. Starts a builder pod according to these rules:
+  - If a `Dockerfile` is present, starts a [`dockerbuilder`](https://github.com/deis/dockerbuilder) pod, configured to download the code to build from the URL computed in the previous step (`dockerbuilder` and Dockerfile builder are not currently supported. See https://github.com/deis/dockerbuilder/pull/1 for prototype `dockerbuilder` code).
+  - Otherwise, starts a [`slugbuilder`](https://github.com/deis/slugbuilder) pod, configured to download the code to build from the URL computed in the previous step.