Something went wrong. Try again.
Dockerfile eDSL, combinators, printer and parser forked from gazagnaire.org/ocaml-dockerfile
Something went wrong. Try again.
31 kB · 782 lines
OCaml
at fixes
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783(* * Copyright (c) 2014 Anil Madhavapeddy <anil@recoil.org> * Copyright (c) 2014 Docker Inc (for the documentation comments, which * have been adapted from https://docs.docker.com/reference/builder) * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * *)
(** Generate [Dockerfile] scripts for use with the Docker container manager. *)
(** {2 Core combinators and serializers} *)
type t(** [t] is a list of Dockerfile lines *)
val to_string : t -> string(** [to_string t] converts a {!t} into a Dockerfile format entry. *)
val pp : t Fmt.t(** [pp] is a formatter that outputs a {!t} in Dockerfile format. *)
module Error = Error(** Parse and interpretation errors, a facade over {!Loc.Error}. *)
val of_string : ?file:string -> string -> (t, Error.t) result(** [of_string s] parses the Dockerfile text [s] into a {!t}. Line continuations are joined, comments and blank lines are handled, and both the shell and exec (JSON-array) forms of [RUN] / [CMD] / [ENTRYPOINT] are recognised.
[Error e] reports a syntax error or an unsupported instruction; [e] carries the source location of the offending line. [file] names the input in error locations (default {!Loc.file_none}). *)
val of_string_exn : ?file:string -> string -> t(** [of_string_exn] is {!of_string} but raises {!Loc.Error.Error} instead of returning a result. *)
type mounttype network = [ `Default | `None | `Host ]type security = [ `Insecure | `Sandbox ]type variable = stringtype port_number = Port_number of int | Port_range of int * int
type port = | Port of { number : port_number; protocol : [ `Udp | `Tcp ] option } | Port_variable of variable
type device
type command = [ `Shell of string | `Exec of string list ](** A run/cmd/entrypoint command, in either the shell or the exec form. *)
(** A BuildKit [RUN --mount=...] mount, curated for consumption. These map onto a builder's own cache / bind / secret notions (e.g. obuilder's cache and secrets). *)type run_mount = | Cache of { target : string; id : string option; readonly : bool option; sharing : [ `Shared | `Private | `Locked ] option; from : string option; source : string option; mode : int option; uid : int option; gid : int option; } | Bind of { target : string; source : string option; from : string option } | Secret of { id : string option; target : string option } | Ssh of { id : string option; target : string option } | Tmpfs of { target : string }
type copy = { from : string option; src : string list; dst : string; chown : string option; chmod : int option;}(** Sources and destination of a [COPY] / [ADD]. The [--from=] argument is a named or numbered earlier build stage, or an external image, that the sources are read from instead of the build context; it is [None] for a copy from the build context. *)
(** A curated, builder-friendly view of one parsed instruction. The raw internal line representation is intentionally not exposed; this surfaces the fields a build front-end needs and folds the rest into {!Other}. *)type instruction = | From of { image : string; tag : string option; alias : string option; platform : string option; } | Run of { command : command; network : network option; security : security option; mounts : run_mount list; } | Cmd of command | Entrypoint of command | Copy of copy | Add of copy | Env of (string * string) list | Arg of string * string option | Label of (string * string) list | Expose of port list | Volume of string list | User of string | Workdir of string | Shell of string list | Maintainer of string | Stopsignal of string | Comment of string | Other of string (** An instruction this view does not type structurally -- a parser directive, here-document [RUN]/[COPY], [HEALTHCHECK], or [ONBUILD] -- carried as its rendered Dockerfile text so a consumer can detect and handle (or reject) it rather than silently dropping it. *)
val instructions : t -> instruction list(** [instructions t] is the curated view of [t]'s instructions, in order. Use it to translate a parsed Dockerfile into another build representation; the multi-command shell form ([RUN a && b]) collapses into a single [`Shell "a && b"]. *)
(** A cursor (list zipper) over a Dockerfile's instructions, for navigating and editing a parsed Dockerfile -- swapping a base image, injecting a step. The focus sits on one instruction (or past the last). Reads surface the curated {!instruction} view; edits splice {!Dockerfile.t} fragments so they go through the same constructors as authoring, and reconstruction is lossless.*)module Cursor : sig type dockerfile = t (** A whole Dockerfile -- alias of {!Dockerfile.t}. *)
type t (** A cursor positioned within a Dockerfile. *)
val v : dockerfile -> t (** [v d] is a cursor over [d], focused on its first instruction. *)
val to_dockerfile : t -> dockerfile (** [to_dockerfile c] reconstructs the Dockerfile, edits included. *)
val length : t -> int (** [length c] is the number of instructions. *)
val index : t -> int (** [index c] is the focus position, [0]-based. Equals {!length} past the end. *)
val focus : t -> instruction option (** [focus c] is the instruction under the cursor, or [None] past the end. *)
val next : t -> t option (** [next c] moves one instruction forward, or [None] at the end. *)
val prev : t -> t option (** [prev c] moves one instruction back, or [None] at the start. *)
val seek : int -> t -> t option (** [seek n c] focuses index [n] ([0]-based; [n = length] is the past-the-end position), or [None] if [n] is out of range. *)
val replace : dockerfile -> t -> t (** [replace frag c] replaces the focused instruction with [frag]'s instructions. A no-op past the end. *)
val insert : dockerfile -> t -> t (** [insert frag c] inserts [frag]'s instructions before the focus. *)
val delete : t -> t option (** [delete c] removes the focused instruction, or [None] past the end. *)end
val ( @@ ) : t -> t -> t(** [a @@ b] concatenates two Dockerfile fragments into one. *)
val ( @@@ ) : t -> t list -> t(** [a @@@ b] concatenates the [b] list of Dockerfile fragments onto [a]. *)
val empty : t(** An empty set of instruction lines. *)
val maybe : ('a -> t) -> 'a option -> t(** [maybe f v] returns {!empty} if the optional value [v] is [None], and otherwise applies [f] to the [Some] value in [v]. *)
(** {2 Dockerfile commands} *)
type parser_directive = [ `Syntax of string | `Escape of char | `Check of string list * bool (** List of check names or [["all"]], and [true] to turn warnings into errors. *) ]
val parser_directive : parser_directive -> t(** A parser directive. If used, needs to be the first line of the Dockerfile. @see <https://docs.docker.com/engine/reference/builder/#parser-directives> Docker parser directives. @see <https://docs.docker.com/build/buildkit/dockerfile-frontend/> BuildKit Dockerfile frontend. *)
val buildkit_syntax : t(** Convenience function, returns the {{!val-parser_directive}parser directive} describing the latest BuildKit syntax. *)
val comment : ('a, Format.formatter, unit, t) format4 -> 'a(** Adds a comment to the Dockerfile for documentation purposes. *)
type heredoc(** Build here-document values with {!val:heredoc}. *)
val heredoc : ?strip:bool -> ?word:string -> ?delimiter:string -> ('a, Format.formatter, unit, heredoc) format4 -> 'a(** [heredoc ~word here_document] creates a {!type:heredoc} value with [here_document] as content and [word] () as opening delimiter. If [word] is quoted, then [delimiter] (unquoted [word]) needs to be specified. Quoting affects expansion in the here-document. Requires 1.4 {!val:buildkit_syntax}.
@param strip Whether to strip leading tab characters. Defaults to false. @param word The opening delimiter, possibly quoted. Defaults to [EOF]. @param delimiter The closing delimiter, unquoted. Defaults to the content of [word].
@see <https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_07_04> POSIX 2.7.4 Here-Document @see <https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#here-documents> BuildKit Here-Documents. *)
val from : ?alias:string -> ?tag:string -> ?platform:string -> string -> t(** The [from] instruction sets the base image for subsequent instructions.
- A valid Dockerfile must have [from] as its first instruction. The image can be any valid image. - [from] must be the first non-comment instruction in the Dockerfile. - [from] can appear multiple times within a single Dockerfile in order to create multiple images. Multiple FROM commands will result in a multi-stage build, and the [?from] argument to the {!copy} and {!add} functions can move artefacts across stages.
By default, the stages are not named, and you refer to them by their integer number, starting with 0 for the first [FROM] instruction. However, you can name your stages, by supplying an [?alias] argument. The alias can be supplied to the [?from] parameter to {!copy} or {!add} to refer to this particular stage by name.
If no [tag] is supplied, [latest] is assumed. If the used tag does not exist, an error will be returned.
The optional [platform] flag can be used to specify the platform of the image in case the [from] references a multi-platform image. For example, [linux/386] could be used. By default, the target platform of the build request is ued if this is not specified. *)
val maintainer : ('a, Format.formatter, unit, t) format4 -> 'a(** [maintainer] sets the author field of the generated images. *)
val run : ?mounts:mount list -> ?network:network -> ?security:security -> ?device:device -> ('a, Format.formatter, unit, t) format4 -> 'a(** [run ?mounts ?network ?security fmt] will execute any commands in a new layer on top of the current image and commit the results. The resulting committed image will be used for the next step in the Dockerfile. The string result of formatting the arguments is passed as a [/bin/sh -c] invocation.
@param mounts A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2.
@param network Control which networking environment the command is run in. Requires {!val:buildkit_syntax} 1.1. Requires BuildKit {{!val:parser_directive}syntax} 1.1.
@param security Control which security mode the command is run in. Requires BuildKit {{!val:parser_directive}syntax} 1-labs.
@param device Lets builds request CDI devices are available to the build step. See {!val-device}. *)
val run_exec : ?mounts:mount list -> ?network:network -> ?security:security -> ?device:device -> string list -> t(** [run_exec ?mounts ?network ?security args] will execute any commands in a new layer on top of current image and commit the results. The resulting committed image will be used for the next step in the Dockerfile. The exec form makes it possible to avoid shell string munging, and to run commands using a base image that does not contain [/bin/sh].
@param mounts A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2.
@param network Control which networking environment the command is run in. Requires {!val:buildkit_syntax} 1.1.
@param security Control which security mode the command is run in. Requires BuildKit {{!val:parser_directive}syntax} 1-labs.
@param device Lets builds request CDI devices are available to the build step. See {!val-device}. *)
val run_heredoc : ?mounts:mount list -> ?network:network -> ?security:security -> ?device:device -> (heredoc * string option) list -> t(** [run_heredoc ?mounts ?network ?security docs] will execute any commands in a new layer on top of the current image and commit the results. The resulting committed image will be used for the next step in the Dockerfile. The string result of formatting the arguments is passed as a [/bin/sh -c] invocation.
@param mounts A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2.
@param network Control which networking environment the command is run in. Requires {!val:buildkit_syntax} 1.1. Requires BuildKit {{!val:parser_directive}syntax} 1.1.
@param security Control which security mode the command is run in. Requires BuildKit {{!val:parser_directive}syntax} 1-labs.
@param device Lets builds request CDI devices are available to the build step. See {!val-device}. *)
val mount_bind : target:string -> ?source:string -> ?from:string -> ?readwrite:bool -> unit -> mount(** [mount_bind ~target ?source ?from ?readwrite ()] Creates a bind mount for {!run}.
Requires {!buildkit_syntax}.
@param target the target of the mount inside the container. Usually a path, but for 'podman' it can also contain SELinux flags like ',z' or ',Z' @param from a build stage to bind mount from (if absent: bind mount host) @param source path to mount. When [from] is absent this is relative to the build context on the host. When [source] is absent it defaults to root of [from]. @param readwrite enables writing to the mount (default: read-only). The data written is not persisted, [source] always remains unchanged.
@see <https://docs.docker.com/engine/ruference/builder/#run---mounttypebind> Docker --mount=type=bind reference. *)
val mount_cache : ?id:string -> target:string -> ?readonly:bool -> ?sharing:[ `Locked | `Private | `Shared ] -> ?from:string -> ?source:string -> ?mode:int -> ?uid:int -> ?gid:int -> unit -> mount(** [mount_cache ?id ~target ?readonly ?sharing ?from ?source ?mode ?uid ?gid ()] Creates a cache mount for {!run}.
Requires {!buildkit_syntax}.
@param id the cache id: all container builds with same cache id (even from other unrelated builds) will get the same writable directory mounted. Defaults to [target] when absent. @param target where to mount the cache inside the container. The [RUN] command needs to cope with a completely empty cache, and with files from the cache being deleted by the container runtime's GC in arbitrary order. E.g. a download cache would be suitable here, an entire git repository wouldn't. Also make sure that your RUN commands doesn't inadvertently wipe the cache (e.g. apt inside a container by default would). @param readonly whether the cache is read-only (by default it is writable) @param sharing how to share the cache between concurrent builds. The default is [`Shared] which doesn't use any locking. @param from the stage to use for the initial contents of the cache. @param source the initial contents of the cache, default is empty. @param mode file mode for cache directory @param uid UID of cache directory, default 0. @param gid GID of cache directory, default 0.
@see <https://docs.docker.com/engine/reference/builder/#run---mounttypecache> Docker --mount=type=cache reference. *)
val mount_tmpfs : target:string -> ?size:int -> unit -> mount(** [mount_tmpfs ~target ?size ())] Creates a tmpfs mount for {!run}.
Requires {!buildkit_syntax}.
@param target mounts a [tmpfs] at [target] @param size maximum size of [tmpfs] (only supported by Docker)
Note that the directory seems to be completely removed from the image, so once you start using [tmpfs] for a dir, it is recommended that all further [RUN] commands use it too to avoid ENOENT errors.
@see <https://docs.docker.com/engine/reference/builder/#run---mounttypetmpfs> Docker --mount=type=tmpfs reference. *)
val mount_secret : ?id:string -> ?target:string -> ?required:bool -> ?mode:int -> ?uid:int -> ?gid:int -> unit -> mount(** [mount_secret ?id ?target ?required ?mode ?uid ?gid] Creates a secret mount for {!run}.
Requires {!buildkit_syntax}.
@see <https://docs.docker.com/engine/reference/builder/#run---mounttypesecret> Docker --mount=type=secret reference. *)
val mount_ssh : ?id:string -> ?target:string -> ?required:bool -> ?mode:int -> ?uid:int -> ?gid:int -> unit -> mount(** [mount_ssh ?id ?target ?required ?mode ?uid ?gid] Creates an ssh mount for {!run}.
Requires {!buildkit_syntax}.
Seems to be only supported by Docker at the moment.
@see <https://docs.docker.com/engine/reference/builder/#run---mounttypessh> Docker --mount=type=ssh reference. *)
val device : name:string -> ?required:bool -> unit -> device(** [device ~name ?required ()] creates a device for [RUN]. Lets builds request CDI devices are available to the build step. *)
val cmd : ('a, Format.formatter, unit, t) format4 -> 'a(** [cmd args] provides defaults for an executing container. These defaults can include an executable, or they can omit the executable, in which case you must specify an {!entrypoint} as well. The string result of formatting the arguments is passed as a [/bin/sh -c] invocation.
There can only be one CMD in a Dockerfile. If you list more than one then only the last one takes effect. *)
val cmd_exec : string list -> t(** [cmd_exec args] provides defaults for an executing container. These defaults can include an executable, or they can omit the executable, in which case you must specify an {!entrypoint} as well. The first argument to the [args] list must be the full path to the executable.
There can only be one CMD in a Dockerfile. If you list more than one then only the last one takes effect. *)
val expose_port : ?protocol:[ `Udp | `Tcp ] -> int -> t(** [expose_port] informs Docker that the container will listen on the specified network port at runtime. *)
val expose_ports : (int * [ `Udp | `Tcp ] option) list -> t(** [expose_ports] informs Docker that the container will listen on the specified network ports at runtime. *)
val arg : ?default:string -> string -> t(** [arg ~default name] defines a variable that users can pass at build-time to the builder with the docker build command using the [--build-arg <varname>=<value>] flag. It can optionally include a default value. *)
val env : (string * string) list -> t(** [env] sets the list of environment variables supplied with the (<key>, <value>) tuple. This value will be passed to all future {!run} instructions. This is functionally equivalent to prefixing a shell command with [<key>=<value>]. *)
val add : ?link:bool -> ?chown:string -> ?chmod:int -> ?from:string -> ?exclude:string list -> ?checksum:string -> ?keep_git_dir:bool -> ?unpack:bool -> src:string list -> dst:string -> unit -> t(** [add ?link ?chown ?chmod ?from ~src ~dst ()] copies new files, directories or remote file URLs from [src] and adds them to the filesystem of the container at the [dst] path.
Multiple [src] resource may be specified but if they are files or directories then they must be relative to the source directory that is being built (the context of the build).
Each [src] may contain wildcards and matching will be done using Go's filepath.Match rules.
All new files and directories are created with a UID and GID of 0. In the case where [src] is a remote file URL, the destination will have permissions of 600. If the remote file being retrieved has an HTTP Last-Modified header, the timestamp from that header will be used to set the mtime on the destination file. Then, like any other file processed during an ADD, mtime will be included in the determination of whether or not the file has changed and the cache should be updated.
@param link Add files with enhanced semantics where your files remain independent on their own layer and don’t get invalidated when commands on previous layers are changed. Requires 1.4 {!val:buildkit_syntax}.
@param chown Specify a given username, groupname, or UID/GID combination to request specific ownership of the copied content.
@param chmod Specify permissions on the files. Only supported on Linux, with Dockerfile syntax 1.3.
@param from Allows artefacts to be retrieved from multiple stages. It can either be an integer number (starting with 0 for the first {!from} stage, or a named stage (supplied via [?alias] to the {!from} command).
@param checksum Verify a remote file checksum.
@param keep_git_dir When cloning a Git repository, the flag adds the [.git] directory. This flag defaults to false.
@param exclude The [--exclude] flag lets you specify a path expression for files to be excluded. The path expression follows the same format as [<src>], supporting wildcards and matching using Go's [filepath.Match] rules.
@param unpack Control whether archives from a URL path are unpacked. The default is to detect unpack behavior based on the source path. *)
val copy : ?link:bool -> ?chown:string -> ?chmod:int -> ?from:string -> ?parents:bool -> ?exclude:string list -> src:string list -> dst:string -> unit -> t(** [copy ?link ?chown ?from ~src ~dst ()] copies new files or directories from [src] and adds them to the filesystem of the container at the path [dst]. See {!add} for more detailed documentation.
@param link Copy files with enhanced semantics where your files remain independent on their own layer and don’t get invalidated when commands on previous layers are changed. Requires 1.4 {!val:buildkit_syntax}.
@param chown Specify a given username, groupname, or UID/GID combination to request specific ownership of the copied content.
@param chmod Specify permissions on the files. Only supported on Linux, with Dockerfile syntax 1.3.
@param from Allows artefacts to be retrieved from multiple stages. It can either be an integer number (starting with 0 for the first {!from} stage, or a named stage (supplied via [?alias] to the {!from} command).
@param parents The [--parents] flag preserves parent directories for [src] entries. This flag defaults to [false].
@param exclude The [--exclude] flag lets you specify a path expression for files to be excluded. The path expression follows the same format as [<src>], supporting wildcards and matching using Go's [filepath.Match] rules. *)
val copy_heredoc : ?chown:string -> ?chmod:int -> src:heredoc list -> dst:string -> unit -> t(** [copy_heredoc ~src ~dst ()] creates the file [dst] using the content of the here-documents [src]. Requires 1.4 {!val:buildkit_syntax}.
@see <https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#here-documents> BuildKit here-documents. *)
val user : ('a, Format.formatter, unit, t) format4 -> 'a(** [user fmt] sets the user name or UID to use when running the image and for any {!run}, {!cmd}, {!entrypoint} commands that follow it in the Dockerfile.*)
val workdir : ('a, Format.formatter, unit, t) format4 -> 'a(** [workdir fmt] sets the working directory for any {!run}, {!cmd} and {!entrypoint} instructions that follow it in the Dockerfile.
It can be used multiple times in the one Dockerfile. If a relative path is provided, it will be relative to the path of the previous {!workdir} instruction. *)
val volume : ('a, Format.formatter, unit, t) format4 -> 'a(** [volume fmt] will create a mount point with the specified name and mark it as holding externally mounted volumes from native host or other containers. The value can be a JSON array or a plain string with multiple arguments that specify several mount points. *)
val volumes : string list -> t(** [volumes mounts] will create mount points with the specified names in [mounts] and mark them as holding externally mounted volumes from native host or other containers. *)
val entrypoint : ('a, Format.formatter, unit, t) format4 -> 'a(** [entrypoint fmt] allows you to configure a container that will run as an executable. The [fmt] string will be executed using a [/bin/sh] subshell.
The shell form prevents any {!cmd} or {!run} command line arguments from being used, but has the disadvantage that your {!entrypoint} will be started as a subcommand of [/bin/sh -c], which does not pass signals. This means that the executable will not be the container's PID 1 - and will not receive Unix signals - so your executable will not receive a SIGTERM from [docker stop <container>].
To get around this limitation, use the {!entrypoint_exec} command to directly execute an argument list without a subshell. *)
val entrypoint_exec : string list -> t(** [entrypoint_exec args] allows you to configure a container that will run as an executable. You can use the exec form here to set fairly stable default commands and arguments and then use either {!cmd} or {!cmd_exec} to set additional defaults that are more likely to be changed by the user starting the Docker container. *)
val shell : string list -> t(** [shell t] allows the default shell used for the shell form of commands to be overridden. The default shell on Linux is ["/bin/sh"; "-c"], and on Windows is ["cmd"; "/S"; "/C"]. The [shell] instruction can appear multiple times. Each [shell] instruction overrides all previous [shell] instructions, and affects all subsequent instructions. *)
val onbuild : t -> t(** [onbuild t] adds to the image a trigger instruction [t] to be executed at a later time, when the image is used as the base for another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the {!from} instruction in the downstream Dockerfile.
Any build instruction can be registered as a trigger.
This is useful if you are building an image which will be used as a base to build other images, for example an application build environment or a daemon which may be customized with user-specific configuration. *)
val label : (string * string) list -> t(** [label l] adds metadata to an image via a list of key-value pairs. To include spaces within a label value, use quotes and backslashes as you would in command-line parsing. An image can have more than one label. To specify multiple labels, Docker recommends combining labels into a single label instruction where possible. Each label instruction produces a new layer which can result in an inefficient image if you use many labels.
Labels are additive including [LABEL]s in [FROM] images. If Docker encounters a label/key that already exists, the new value overrides any previous labels with identical keys.
To view an image’s labels, use the [docker inspect] command. *)
val healthcheck : ?interval:string -> ?timeout:string -> ?start_period:string -> ?start_interval:string -> ?retries:int -> ('a, Format.formatter, unit, t) format4 -> 'a(** [healthcheck cmd] checks container health by running a command inside the container. See {!cmd} for additional details.
@param interval The health check will first run [interval] seconds after the container is started, and then again [interval] seconds after each previous check completes.
@param timeout If a single run of the check takes longer than [timeout] seconds then the check is considered to have failed.
@param start_period provides initialization time for containers that need time to bootstrap. Probe failure during that period will not be counted towards the maximum number of retries. However, if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries.
@param start_interval is the time between health checks during the start period.
@param retries It takes [retries] consecutive failures of the health check for the container to be considered {i unhealthy}. *)
val healthcheck_exec : ?interval:string -> ?timeout:string -> ?start_period:string -> ?start_interval:string -> ?retries:int -> string list -> t(** [healthcheck_exec cmd] checks container health by running a command inside the container. See {!cmd_exec} and {!healthcheck} for additional details. *)
val healthcheck_none : unit -> t(** [healthcheck_none] disables any healthcheck inherited from the base image.*)
val stopsignal : string -> t(** [stopsignal signal] sets the system call signal that will be sent to the container to exit. *)
val crunch : t -> t(** [crunch t] will reduce coincident {!run} commands into a single one that is chained using the shell [&&] operator. This reduces the number of layers required for a production image.
@raise Invalid_argument if mounts or networks or security modes differ for each run command. *)
val layers : t -> int(** [layers t] approximates the number of layers that would be produced by the Docker build of this Dockerfile. Each {!from}, {!run}, {!copy}, {!add} command produces a new layer. *)