Endiafile

A recipe is an Endiafile: a file written in Dockerfile syntax. East India reads the subset below and refuses everything else before any virtual machine starts, naming the file, line and column as a compiler does, for example recipes/dotnet.Endiafile:3:1: HEALTHCHECK is not supported in this release.

File names

A folder with one recipe names it Endiafile; a folder with several names each name.Endiafile, such as recipes/dotnet.Endiafile. The name changes nothing else, so a Dockerfile written for Docker is a recipe under either name. A build without -f reads Endiafile and otherwise Dockerfile; -f takes a file of any name, such as an existing name.Dockerfile.

Syntax

Syntax is Docker's. Keywords are case-insensitive, and # at the start of a line begins a comment. Lines end in LF or CRLF, and a leading byte-order mark is ignored. The escape character at the end of a line continues the instruction on the next line, and comment or blank lines inside a continuation are dropped. The parser directive # escape= followed by \ (the default) or a backtick is read only before the first instruction, comment or blank line. The directives # syntax= and # check= are refused with UNSUPPORTED_FIELD. A recipe larger than 1 MiB, or not valid UTF-8, is refused with INVALID_DEFINITION.

Layout and stages

A recipe has optional ARG instructions, then one or more stages. Each stage begins with a FROM and runs to the next FROM or the end of the recipe. An instruction other than ARG before the first FROM is refused with INVALID_DEFINITION.

FROM <name> names an earlier stage when an earlier FROM ... AS <name> gave that name, and an image otherwise, as in Docker; a stage cannot name itself or a later stage. A stage built FROM an earlier stage starts from that stage's result, with its configuration and labels. A stage name matches [a-z][a-z0-9._-]* once lower-cased, and names compare without regard to case. Any other name is refused with INVALID_DEFINITION, and so is a name that two stages share.

A build makes its target stage, --target or the last stage, and the stages its FROM lines pass through. It checks the other stages but does not build them, as Docker's BuildKit skips them. An ARG before the first FROM is visible only to FROM lines, and a stage sees a build argument only after its own ARG for it. A stage's variables end with the stage, so a later stage receives only what its parent's configuration holds, such as ENV.

One layer per stage, not per instruction

East India caches and commits each stage as a whole. A change to any step of a stage reruns every step of that stage and of every stage built on it. Layers, stages and the build cache explains why, and how to split a recipe.

Instructions

Instruction Behaviour in a Windows build
FROM <image or stage> [AS <name>] Begins a stage and names its parent: an earlier stage, or any image reference. A reference to no image fails the build with NOT_FOUND. AS <name> names the stage. Flags such as --platform are refused.
ARG <name>[=<default>] Declares a build argument. Before FROM, it is visible only to FROM; after FROM, from its own line on. ARG <name> after FROM without a default takes the value of the same ARG before FROM.
ENV <key>=<value> ... or ENV <key> <value> Sets environment variables for later steps and for the image's configuration.
LABEL <key>=<value> ... Adds labels.
WORKDIR <path> Sets the working folder for later steps and for the image's configuration, and creates it in the build machine if missing. A relative path is relative to the previous WORKDIR. The default is C:\.
SHELL ["<executable>", "<argument>", ...] Sets the shell for the shell form of RUN, CMD and ENTRYPOINT. The default is ["cmd", "/S", "/C"]. Only the JSON form is accepted.
RUN <command> or RUN ["<executable>", "<argument>", ...] Runs a program in the builder. Flags such as --mount, and here-documents, are refused.
COPY <source>... <destination> Copies files from the build context into the builder. Flags (--from, --chown, --chmod, --link, --parents, --exclude) and URLs are refused.
USER <user> Names the account that later RUN steps run as. Machines made from the image also run their main process as that account, as in Docker, and a child image inherits it. SYSTEM (case-insensitive), and no USER, run as SYSTEM. COPY and WORKDIR are unaffected. A RUN step whose account does not exist fails with BUILD_FAILED and Docker's message unable to find user <name>.
EXPOSE <port>[/tcp] ... Records ports in the configuration. It opens nothing. /udp is refused.
ENTRYPOINT and CMD Set the image's main process, in JSON or shell form, by Docker's rules: the shell form runs through the shell; CMD supplies default arguments to a JSON-form ENTRYPOINT; a shell-form ENTRYPOINT ignores CMD; an ENTRYPOINT instruction clears an earlier CMD.
ADD, VOLUME, HEALTHCHECK, ONBUILD, STOPSIGNAL, MAINTAINER Refused with UNSUPPORTED_FIELD.

Words, quoting and variables

JSON form. A JSON array of strings, as in Docker. An argument that is not a valid JSON array of strings is read as the shell form, as Docker reads it.

Words and quoting. Inside ENV, LABEL, ARG, WORKDIR, COPY, USER and EXPOSE, single quotes are literal. Double quotes group words and remove the escape character before ", $ and the escape character itself. Outside quotes, the escape character makes the next character literal.

Variable expansion. $NAME, ${NAME}, ${NAME:-word} (the value, or word when unset or empty) and ${NAME:+word} (word when set and not empty, otherwise nothing) are expanded in FROM, ARG defaults, ENV, LABEL, WORKDIR, COPY sources and destination, USER and EXPOSE. The escape character before $ keeps it literal. East India does not expand RUN, CMD, ENTRYPOINT or SHELL; the shell expands RUN.

Ignore files

A build uses the first of these that exists, and no other:

  1. <recipe file name>.endiaignore beside the recipe;
  2. <recipe file name>.dockerignore beside the recipe;
  3. .endiaignore at the root of the build context;
  4. .dockerignore at the root.

Its patterns follow Docker's .dockerignore rules.

Build steps