github.com/techend/deis@v1.0.1-0.20141111224634-e0eee0392b8a/builder/slugbuilder/README.md (about)

     1  # (Heroku-ish) Slug Builder
     2  
     3  A tool using [Docker](http://docker.io) and
     4  [Buildpacks](https://devcenter.heroku.com/articles/buildpacks) to produce a Heroku-like
     5  [slug](https://devcenter.heroku.com/articles/slug-compiler) given some application source.
     6  
     7  ## What does it do exactly?
     8  
     9  It's a Docker container that takes an uncompressed tarball of an application source piped to it.
    10  The source is run through buildpacks, then if it's detected as a supported app it will be compiled
    11  into a gzipped tarball ready to be run somewhere.
    12  
    13  ## Using Slug Builder
    14  
    15  First, you need Docker. Then you can either pull the image from the public index:
    16  
    17  	$ docker pull deis/slugbuilder
    18  
    19  Or you can build from this source:
    20  
    21  	$ cd slugbuilder
    22  	$ make
    23  
    24  When you run the container, it always expects a tar of your app source to be passed via stdin. So
    25  let's run it from a git repo and use `git archive` to produce a tar:
    26  
    27  	$ id=$(git archive master | docker run -i -a stdin deis/slugbuilder)
    28  	$ docker wait $id
    29  	$ docker cp $id:/tmp/slug.tgz .
    30  
    31  We run slugbuilder, wait for it to finish using the id it gave us, then copies out the slug
    32  artifact into the current directory. If we attached to the container with `docker attach` we could
    33  also see the build output as you would with Heroku. We can also *just* see the build output by
    34  running it with stdout:
    35  
    36  	$ git archive master | docker run -i -a stdin -a stdout deis/slugbuilder
    37  
    38  We still have to look up the id and copy the slug out of the container, but there's an easier way!
    39  
    40  	$ git archive master | docker run -i -a stdin -a stdout deis/slugbuilder - > myslug.tgz
    41  
    42  By running with the `-` argument, it will send all build output to stderr (which we didn't attach
    43  here) and then spit out the slug to stdout, which as you can see we can easily redirect into a
    44  file.
    45  
    46  Lastly, you can also have it PUT the slug somewhere via HTTP if you give it a URL as an argument.
    47  This lets us specify a place to put it *and* get the build output via stdout:
    48  
    49  	$ git archive master | docker run -i -a stdin -a stdout deis/slugbuilder http://fileserver/path/for/myslug.tgz
    50  
    51  ## Caching
    52  
    53  To speed up slug building, it's best to mount a volume specific to your app at `/tmp/cache`. For
    54  example, if you wanted to keep the cache for this app on your host at `/tmp/app-cache`, you'd mount
    55  a read-write volume by running docker with this added `-v /tmp/app-cache:/tmp/cache:rw` option:
    56  
    57  	docker run -v /tmp/app-cache:/tmp/cache:rw -i -a stdin -a stdout deis/slugbuilder
    58  
    59  
    60  ## Buildpacks
    61  
    62  As you can see, slugbuilder supports a number of official and third-party Heroku buildpacks. You
    63  can change the buildpacks.txt file and rebuild the container to create a version that supports
    64  more/less buildpacks than we do here. You can also bind mount your own directory of buildpacks if
    65  you'd like:
    66  
    67  	docker run -v /my/buildpacks:/tmp/buildpacks:ro -i -a stdin -a stdout deis/slugbuilder
    68  
    69  ## Base Environment
    70  
    71  The Docker image here is based on [cedarish](https://github.com/progrium/cedarish), an image that
    72  emulates the Heroku Cedar stack environment. All buildpacks should have everything they need to run
    73  in this environment, but if something is missing it should be added upstream to cedarish.