Merge pull request #530 from convox/build-plus-plus

#507 Build Provider Refactor
#496 warn if app contains unignored env
#514 don't panic on malformed labels
#529 Add support for passing existing IAM/ACM arn to convox ssl create/update commands
#526 run specific release

api/cmd/build/Makefile

@@ -0,0 +1,3 @@
+main:
+	go-bindata data/
+	go build main.go

api/cmd/build/README.md

@@ -1,8 +1,71 @@
-# convox/build
+# build
 
-Build and push Docker images for Convox apps
+Build, tag and push Docker images from an app's source.
 
-## Development
+Source is either a .tgz snapshot of an app directory or an URL to a git
+repository and optional commit.
+
+This command is designed to run in the convox/rack Docker image which is a
+basic Linux environment with `docker`, `git`, and `ssh` available for extracting
+or cloning the app source.
+
+## Usage
+
+```
+$ tar cz | build -
+$ build github.com/convox-examples/sinatra.git
+```
+
+## Docker Run Flags
+
+* `-v /var/run/docker.sock:/var/run/docker.sock` so it can acess the Docker daemon and execute `docker build`
+* `-i` so it can read .tgz data from stdin
+
+## Environment
+
+This command tags images in a way that reflects a specific app and build id. Therefore these arguments
+are required:
+
+* `APP` - Name of the app we are building for
+* `BUILD` - Id of the build
+* `REGISTRY_ADDRESS` - Registry host to tag and push to
+
+And the tag namespace is optional:
+
+* `REPOSITORY` - Optional namespace that every image should use
+
+Without `REPOSITORY`, tags use the app name as the repository, the process name as the image name, and the build id as the tag:
+
+```
+convox-826133048.us-east-1.elb.amazonaws.com:5000/sinatra/web:BANHPORIOTL 
+```
+
+With `REPOSITORY`, tags always share the same repository, and use the process name and build id as the tag:
+
+```
+132866487567.dkr.ecr.us-east-1.amazonaws.com/convox-sinatra-soppqmvrdv:web.BDQBBSNVTZD
+```
+
+This command may pull images that docker-compose.yml references, and will push new images to a remote registry.
+These arguments along with `REGISTRY_ADDRESS` offer Docker authentication to push/pull:
+
+* `DOCKER_AUTH` - Json blob of private registry auth info
+* `REGISTRY_EMAIL` - Credentials to `docker push`
+* `REGISTRY_USERNAME` - Credentials to `docker push`
+* `REGISTRY_PASSWORD` - Credentials to `docker push`
+
+If this command calls back to Rack to denote build status. Any error calls back to report "failed",
+otherwise it reports "complete". These arguments offer Rack authentication to call back:
+
+* `RACK_HOST` - Hostname to call back on build success or failure
+* `RACK_PASSWORD` - Password to call back on build success or failure
+
+A few options of the build are controlled by a user. These arguments override default assumptions for `docker build`:
+
+* `MANIFEST_PATH` - Optional path if not docker-compose.yml
+* `NO_CACHE` - Option to build without reusing cache
+
+## Examples
 
     # rebuild the API image and build cmd
 
@@ -15,102 +78,4 @@ Build and push Docker images for Convox apps
 
     $ cd httpd
     $ tar cz . | docker run -i -v /var/run/docker.sock:/var/run/docker.sock rack/api \
-      build httpd -
-
-    manifest|web:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 80:80
-    manifest|  - 443:80
-    manifest|web2:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 8000:80
-    build|RUNNING: docker tag -f httpd httpd/web
-
-    # build a directory as long as its mounted into the container
-
-    $ cd httpd
-    $ docker run -i -v /var/run/docker.sock:/var/run/docker.sock -v $(pwd):/tmp/app rack/api \
-      build httpd /tmp/app
-
-    manifest|web:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 80:80
-    manifest|  - 443:80
-    manifest|web2:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 8000:80
-    build|RUNNING: docker tag -f httpd httpd/web
-
-    # build an http git repo
-
-    $ docker run -i -v /var/run/docker.sock:/var/run/docker.sock rack/api \
-      build httpd https://github.com/nzoschke/httpd.git
-
-    git|Cloning into '/tmp/repo655149862/clone'...
-    git|POST git-upload-pack (190 bytes)
-    git|remote: Counting objects: 20, done.
-    remote: Compressing objects: 100% (16/16), done.
-    git|remote: Total 20 (delta 11), reused 11 (delta 2), pack-reused 0
-    git|Checking connectivity... done.
-    manifest|web:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 80:80
-    build|RUNNING: docker tag -f httpd httpd/web
-
-    # build a git repo with a commit-ish
-
-    $ docker run -i -v /var/run/docker.sock:/var/run/docker.sock rack/api \
-      build httpd https://github.com/nzoschke/httpd.git#thunk
-
-    git|Cloning into '/tmp/repo824977679/clone'...
-    git|POST git-upload-pack (190 bytes)
-    git|remote: Counting objects: 20, done.
-    remote: Compressing objects: 100% (16/16), done.
-    git|remote: Total 20 (delta 11), reused 11 (delta 2), pack-reused 0
-    git|Checking connectivity... done.
-    git|error: pathspec 'thunk' did not match any file(s) known to git.
-    ERROR: exit status 1
-
-    # try an SSH git repo
-
-    $ docker run -i -v /var/run/docker.sock:/var/run/docker.sock rack/api \
-      build httpd ssh://[email protected]:nzoschke/httpd.git
-
-    git|Cloning into '/tmp/repo295143718/clone'...
-    git|Warning: Permanently added 'gitlab.com,104.210.2.228' (ECDSA) to the list of known hosts.
-    git|Permission denied (publickey).
-    git|fatal: Could not read from remote repository.
-    git|
-    git|Please make sure you have the correct access rights
-    git|and the repository exists.
-    ERROR: exit status 128
-    2016/03/09 22:47:54 exit status 1
-
-    # build an SSH git repo by passing in a public key that's configured as an SSH deploy key
-
-    $ KEY=$(base64 /tmp/id_rsa)
-    $ docker run -i -v /var/run/docker.sock:/var/run/docker.sock rack/api \
-      build httpd ssh://git:[email protected]:nzoschke/httpd.git
-
-    git|Cloning into '/tmp/repo839273553/clone'...
-    git|Warning: Permanently added 'gitlab.com,104.210.2.228' (ECDSA) to the list of known hosts.
-    git|remote: Counting objects: 10, done.
-    remote: Compressing objects: 100% (8/8), done.
-    git|remote: Total 10 (delta 3), reused 0 (delta 0)
-    Receiving objects: 100% (10/10), done.
-    Resolving deltas: 100% (3/3), done.
-    git|Checking connectivity... done.
-    manifest|web:
-    manifest|  image: httpd
-    manifest|  ports:
-    manifest|  - 80:80
-    build|RUNNING: docker tag -f httpd httpd/web
-
-## License
-
-Apache 2.0 © 2015 Convox, Inc.
+      build httpd -