-
-
Save erikh/0e791230c72a2c71baa5 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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