diff --git a/README.md b/README.md index a8e3ea1e..b8ff75f8 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Some highlights of Makisu: * Requires no elevated privileges or containerd/Docker daemon, making the build process portable. * Uses a distributed layer cache to improve performance across a build cluster. * Provides control over generated layers with a new optional keyword [`#!COMMIT`](#explicit-commit-and-cache), reducing the number of layers in images. -* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](lib/parser/dockerfile/README.md). +* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](docs/PARSER.md). Makisu has been in use at Uber since early 2018, building thousands of images every day across 4 different languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/. @@ -53,7 +53,7 @@ makisu build -t ${TAG} --dest ${TAR_PATH} ${CONTEXT} # Running Makisu -For a full list of flags, run `makisu build --help` or refer to the README [here](bin/makisu/README.md). +For a full list of flags, run `makisu build --help` or refer to the README [here](docs/COMMAND.md). ## Makisu anywhere diff --git a/bin/makisu/README.md b/docs/COMMAND.md similarity index 90% rename from bin/makisu/README.md rename to docs/COMMAND.md index 8187872f..6d2d31f8 100644 --- a/bin/makisu/README.md +++ b/docs/COMMAND.md @@ -12,15 +12,17 @@ Flags: -f, --file string The absolute path to the dockerfile (default "Dockerfile") -t, --tag string Image tag (required) --push stringArray Registry to push image to + --replica stringArray Push targets with alternative full image names "/:" --registry-config string Set build-time variables --dest string Destination of the image tar + --target string Set the target build stage to build. --build-arg stringArray Argument to the dockerfile as per the spec of ARG. Format is "--build-arg =" --modifyfs Allow makisu to modify files outside of its internal storage dir --commit string Set to explicit to only commit at steps with '#!COMMIT' annotations; Set to implicit to commit at every ADD/COPY/RUN step (default "implicit") --blacklist stringArray Makisu will ignore all changes to these locations in the resulting docker images --local-cache-ttl duration Time-To-Live for local cache (default 168h0m0s) --redis-cache-addr string The address of a redis server for cacheID to layer sha mapping - --redis-cache-password string The password of the Redis server, should match 'requirepass' in redis.conf + --redis-cache-password string The password of the Redis server, should match 'requirepass' in redis.conf --redis-cache-ttl duration Time-To-Live for redis cache (default 168h0m0s) --http-cache-addr string The address of the http server for cacheID to layer sha mapping --http-cache-header stringArray Request header for http cache server. Format is "--http-cache-header
:" @@ -30,6 +32,7 @@ Flags: --load Load image into docker daemon after build. Requires access to docker socket at location defined by ${DOCKER_HOST} --storage string Directory that makisu uses for temp files and cached layers. Mount this path for better caching performance. If modifyfs is set, default to /makisu-storage; Otherwise default to /tmp/makisu-storage --compression string Image compression level, could be 'no', 'speed', 'size', 'default' (default "default") + --preserve-root Copy / in the storage dir and copy it back after build. -h, --help help for build Global Flags: diff --git a/lib/parser/dockerfile/README.md b/docs/PARSER.md similarity index 93% rename from lib/parser/dockerfile/README.md rename to docs/PARSER.md index f7fd94fa..abdb21d3 100644 --- a/lib/parser/dockerfile/README.md +++ b/docs/PARSER.md @@ -29,7 +29,7 @@ The following directives are not supported: ONBUILD and SHELL. Syntax: - #!COMMIT - 'COMMIT' can be any case and there can be whitespace preceding '#', after '!', or after 'COMMIT'. - - It cannot be at the beginning of a line, since all lines beginning with '#' would be ignored. + - It cannot be at the beginning of a line, since all lines beginning with '#' would be ignored. This is a special directive that indicates that a layer should be committed (used in the distributed cache). To enable this directive, `--commit=explicit` argument is required. @@ -59,12 +59,13 @@ Variables are substituted using values from ARGs and ENVs within the stage. ## COPY Syntax: -- COPY \[--chown=\:\\] \[--from=\\] \ ... \ +- COPY \[--chown=\:\\] \[--from=\\] \[--archive\] \ ... \ - Arguments must be separated by whitespace. -- COPY \[--chown=\:\\] \[--from=\\] \["\",... "\"\] (this form is required for paths containing whitespace) +- COPY \[--chown=\:\\] \[--from=\\] \[--archive\] \["\",... "\"\] (this form is required for paths containing whitespace) - JSON format. Variables are substituted using values from ARGs and ENVs within the stage. +`--archive` is a makisu-specific option. By default, makisu will follow docker's behavior, where `dst` itself might be owned by root if not created beforehand. Adding `--archive` will make COPY preserve the original owner and permissions of `src` and its underlying files and directories. ## ENTRYPOINT diff --git a/docs/index.md b/docs/index.md index df65b873..8f7b8a94 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ Some highlights of Makisu: * Requires no elevated privileges or containerd/Docker daemon, making the build process portable. * Uses a distributed layer cache to improve performance across a build cluster. * Provides control over generated layers with a new optional keyword [`#!COMMIT`](#explicit-commit-and-cache), reducing the number of layers in images. -* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](lib/parser/dockerfile/README.md). +* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](docs/PARSER.md). Makisu has been in use at Uber since early 2018, building thousands of images every day across 4 different languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/. @@ -53,7 +53,7 @@ makisu build -t ${TAG} --dest ${TAR_PATH} ${CONTEXT} # Running Makisu -For a full list of flags, run `makisu build --help` or refer to the README [here](bin/makisu/README.md). +For a full list of flags, run `makisu build --help` or refer to the README [here](docs/COMMAND.md). ## Makisu anywhere diff --git a/site/index.html b/site/index.html index 3bcd90ff..fb4ee0bb 100644 --- a/site/index.html +++ b/site/index.html @@ -178,7 +178,7 @@ * Provides control over generated layers with a new optional keyword #!COMMIT, reducing the number of layers in images. * Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More - details can be found here.

+ details can be found here.

Makisu has been in use at Uber since early 2018, building thousands of images every day across 4 different languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/.

@@ -214,7 +214,7 @@

Building Makisu binary a

Running Makisu

For a full list of flags, run makisu build --help or refer to the README here.

+ href="docs/COMMAND.md">here.

Makisu anywhere

To build Dockerfiles that contain RUN, Makisu needs to run in a container. To try it locally, the following snippet can be placed inside your ~/.bashrc or