Skip to content

Instantly share code, notes, and snippets.

@erikh

erikh/stdin Secret

Created October 31, 2014 01:54
Show Gist options
  • Save erikh/0e791230c72a2c71baa5 to your computer and use it in GitHub Desktop.
Save erikh/0e791230c72a2c71baa5 to your computer and use it in GitHub Desktop.
diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md
index 4bb02e3..eadadf0 100644
--- a/docs/sources/reference/builder.md
+++ b/docs/sources/reference/builder.md
@@ -166,6 +166,110 @@ used tag does not exist, an error will be returned.
The `MAINTAINER` instruction allows you to set the *Author* field of the
generated images.
+## START
+
+`START` accepts a single argument -- any program path -- which is used to
+configure the image. Instructions may follow after this one and will execute
+after the program has successfully executed and terminated. A single layer is
+committed after `START` similarly to other `Dockerfile` instructions.
+
+`Program` refers to any binary, script, etc that exists in the build context
+that can be executed by a running container. A special container will be
+created for building, and the toolkit below, or the API, can be used to perform
+operations on the image.
+
+This instruction is complicated to use, but very powerful as it allows you to
+use any program or tool of your choice to configure images; programs that could
+make remote API calls, implement advanced templating logic, or anything really.
+If you are not sure you need this, stick with Dockerfiles.
+
+The program can leverage a toolkit that is injected into the container's
+filesystem at `/docker/docker-toolkit`, which will be at the head of the `PATH`
+environment variable for easy location. This toolkit is composed of several
+binaries which communicate with the Docker daemon and perform actions.
+
+The commands (each has a --help option):
+
+* `build`: process a Docker build repository (git, tar, directory) which will
+ also populate the image. This is called a "nested" or "recursive" build.
+* `envset`: tell the Docker engine to populate environment variables on `docker
+ run`.
+* `onbuild`: tell the Docker engine to perform an instruction when built on top
+ via a `FROM` instruction.
+* `download`: Download a file over http(s).
+* `cmd`: Equivalent to the `CMD` instruction.
+* `entrypoint`: Equivalent to the `ENTRYPOINT` instruction.
+* `expose`: Equivalent to the `EXPOSE` instruction.
+* `volume`: Equivalent to the `VOLUME` instruction.
+* `user`: Equivalent to the `USER` instruction.
+* `copy`: Equivalent to the `COPY` instruction. Allows populating the image
+ with files.
+* `mount`: mount a directory within the image container.
+* `run`: run a command on the image container.
+
+Likewise, the build context will be uploaded to `/docker/docker-context`,
+allowing you to perform standard operating system commands with it such as `rm`
+or `cp`.
+
+Both the context and the toolkit are removed after the build has finished.
+
+### Build Context
+
+The build context will live at `/docker/docker-build` and contain all the files
+from the build context. You can manipulate these files before transferring them
+to the image container just like you would with normal Unix tools such as
+`sed`, `awk`, or `perl`. What is available depends on the image you use to
+build with.
+
+### Build and Image Containers
+
+The outermost build process (in the event builds are nested) will create two
+containers: a "build" container containing the build context and the build
+toolkit, and an "image" container which represents the final image result. You
+can use the toolkit to program settings for the image as well as copy files
+from the build container to the image container or run statements there. The
+separation of concerns allows you to do preparatory work before shipping the
+files to the image.
+
+### WORKDIR
+
+As hinted at above, all context and toolkit files will be installed under
+`WORKDIR` if it is provided **before** the `START` instruction is executed.
+
+### Caching
+
+Cache keys are generated from the SHA-512 sum of the referenced script's
+contents. `START` generates one layer, just like most `Dockerfile`
+instructions.
+
+If you wish to leverage caching with multiple layers, consider dividing your
+program into multiple programs invoked by multiple `START` lines.
+
+###
+
+### Examples
+
+Let's imagine a build context that looks like this:
+
+ /myfile
+ /build.sh
+
+`build.sh` looks like this:
+
+ #!/bin/sh
+ copy myfile /
+
+Which uses the `copy` tool provided in the docker toolkit. This will already
+exist in the `PATH` environment variable so there is no need to fully qualify it.
+
+With this Dockerfile:
+
+ FROM busybox
+ START build.sh
+
+This copies the file `myfile` from the build container to `/` in the image
+container.
+
## RUN
RUN has 2 forms:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment