package dockerfile

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Generate Dockerfile scripts for use with the Docker container manager

Core combinators and serializers

type t

t is a list of Dockerfile lines

val sexp_of_t : t -> Sexplib.Sexp.t

sexp_of_t t converts a Dockerfile into a s-expression representation.

val t_of_sexp : Sexplib.Sexp.t -> t

t_of_sexp s converts the s s-expression representation into a t. The s-expression should have been generated using sexp_of_t.

val string_of_t : t -> string

string_of_t 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.

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.

Dockerfile commands

type parser_directive = [
  1. | `Syntax of string
  2. | `Escape of char
]
val sexp_of_parser_directive : parser_directive -> Ppx_sexp_conv_lib.Sexp.t
val parser_directive_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> parser_directive
val __parser_directive_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> parser_directive
val parser_directive : parser_directive -> t

A parser directive. If used, needs to be the first line of the Dockerfile.

val buildkit_syntax : t

Convenience function, returns the parser directive describing the latest BuildKit syntax.

val comment : ('a, unit, string, t) Stdlib.format4 -> 'a

Adds a comment to the Dockerfile for documentation purposes

type heredoc

Build here-document values with heredoc.

val heredoc : ?strip:bool -> ?word:string -> ?delimiter:string -> ('a, unit, string, heredoc) Stdlib.format4 -> 'a

heredoc ~word here_document creates a 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 buildkit_syntax.

  • parameter strip

    Whether to strip leading tab characters. Defaults to false.

  • parameter word

    The opening delimiter, possibly quoted. Defaults to EOF.

  • parameter delimiter

    The closing delimiter, unquoted. Defaults to the content of word.

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, unit, string, t) Stdlib.format4 -> 'a

maintainer sets the author field of the generated images.

type mount
type network = [
  1. | `Default
  2. | `None
  3. | `Host
]
type security = [
  1. | `Insecure
  2. | `Sandbox
]
val run : ?mounts:mount list -> ?network:network -> ?security:security -> ('a, unit, string, t) Stdlib.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 arg will be passed as a /bin/sh -c invocation.

  • parameter mounts

    A list of filesystem mounts that the build can access. Requires buildkit_syntax 1.2.

  • parameter network

    Control which networking environment the command is run in. Requires buildkit_syntax 1.1. Requires BuildKit syntax 1.1.

  • parameter security

    Control which security mode the command is run in. Requires BuildKit syntax 1-labs.

val run_exec : ?mounts:mount list -> ?network:network -> ?security:security -> 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 cmd form makes it possible to avoid shell string munging, and to run commands using a base image that does not contain /bin/sh.

  • parameter mounts

    A list of filesystem mounts that the build can access. Requires buildkit_syntax 1.2.

  • parameter network

    Control which networking environment the command is run in. Requires buildkit_syntax 1.1.

  • parameter security

    Control which security mode the command is run in. Requires BuildKit syntax 1-labs.

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.

  • parameter 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'

  • parameter from

    a build stage to bind mount from (if absent: bind mount host)

  • parameter 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.

  • parameter readwrite

    enables writing to the mount (default: read-only). The data written is not persisted, source always remains unchanged.

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.

  • parameter 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.

  • parameter 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).

  • parameter readonly

    whether the cache is read-only (by default it is writable)

  • parameter sharing

    how to share the cache between concurrent builds. The default is `Shared which doesn't use any locking.

  • parameter from

    the stage to use for the initial contents of the cache.

  • parameter source

    the initial contents of the cache, default is empty.

  • parameter mode

    file mode for cache directory

  • parameter uid

    UID of cache directory, default 0.

  • parameter gid

    GID of cache directory, default 0.

val mount_tmpfs : target:string -> ?size:int -> unit -> mount

mount_tmpfs ~target ?size ()) Creates a tmpfs mount for run.

Requires buildkit_syntax.

  • parameter target

    mounts a tmpfs at target

  • parameter 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.

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.

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.

val cmd : ('a, unit, string, t) Stdlib.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 arg will be 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 cmd will take 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 cmd will take effect.

val expose_port : int -> t

expose_port informs Docker that the container will listen on the specified network port at runtime.

val expose_ports : int 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 -> ?from:string -> src:string list -> dst:string -> unit -> t

add ?link ?chown ?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.

  • parameter 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 buildkit_syntax.

  • parameter chown

    Specify a given username, groupname, or UID/GID combination to request specific ownership of the copied content.

  • parameter 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).

val copy : ?link:bool -> ?chown:string -> ?from:string -> 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.

  • parameter 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 buildkit_syntax.

  • parameter chown

    Specify a given username, groupname, or UID/GID combination to request specific ownership of the copied content.

  • parameter 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).

val copy_heredoc : ?chown:string -> 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 buildkit_syntax.

val user : ('a, unit, string, t) Stdlib.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, unit, string, t) Stdlib.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, unit, string, t) Stdlib.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, unit, string, t) Stdlib.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 fmt 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 LABELs 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 -> ?retries:int -> ('a, unit, string, t) Stdlib.format4 -> 'a

healthcheck cmd checks container health by running a command inside the container. See cmd for additional details.

  • parameter interval

    The health check will first run interval seconds after the container is started, and then again interval seconds after each previous check completes.

  • parameter timeout

    If a single run of the check takes longer than timeout seconds then the check is considered to have failed.

  • parameter retries

    It takes retries consecutive failures of the health check for the container to be considered unhealthy.

  • parameter 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.

val healthcheck_exec : ?interval:string -> ?timeout:string -> ?start_period: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.

  • raises Invalid_argument

    if mounts or networks or security modes differ for each run command.

OCaml

Innovation. Community. Security.