dockerfile

README

For the most part, this parser is compatible with the official Docker parser. However, there are a few unintuitive behaviors present in the Docker parser that have been replaced here.

Variable substitution

All supported directives allow variable substitution from both ARG and ENV directives.

Valid variable names consist of {letters, digits, '-', '_', '.'}, and variable values can contain any character.

Variable substitutions can be specified in the following formats:

• $<var>
  • Terminates once an invalid variable name character is encountered (e.g., if var=val1 and var_=val2, /$var/ -> /val1/ and _$var_ -> _$val2).
• ${<var>}
  • Supports recursive variable resolution (e.g., if var=val1 and val1=val2, ${$var} -> val2).
• ${<var>:+<default_val>}
  • If <var> not set, resolves to <default_val>, else the value for <var>. <var> may contain variables to resolve, but <default_val> may not.
• ${<var>:-<default_val>}
  • If <var> set, resolves to <default_val>, else the empty string. <var> may contain variables to resolve, but <default_val> may not.

If a variable fails to resolve, it is passed through to the resulting string exactly as it appears in the input.

Inline comments and backslash

Makisu supports inline comments and backslashes in general, but not if the comment is between multiple lines of one RUN directive separated by backslash. For example, these instructions are supported:

# Print hello
RUN echo \
  hello
# Print world
RUN echo \
  world

RUN echo \
  hello # Print hello
RUN echo \
  world # Print world

# Print hello
RUN echo \
  hello
# Print world
RUN echo \
  world

But the following is not supported:

RUN echo \
# Print hello
  hello

This is because #!COMMIT is a special keyword for Makisu, we don't know how to handle it if #!COMMIT is placed in the middle of a RUN directive; Besides, backslash is supposed to mean "ignore next character" in bash, so the above example is supposed to be equivalent to:

RUN echo # Print hello
  hello

It doesn't seem reasonable to accept such a Dockerfile.

Directives

The following directives are not supported: ONBUILD, HEALTHCHECK, and SHELL.

COMMIT

Syntax:

• #!COMMIT
  • 'COMMIT' can be any case and there can be whitespace preceding '#', after '!', or after 'COMMIT.'

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.

ADD

Syntax:

• ADD [--chown=<user>:<group>] <src> ... <dest>
  • Arguments must be separated by whitespace.
• ADD [--chown=<user>:<group>] ["<src>",... "<dest>"] (this form is required for paths containing whitespace)
  • JSON format.

Variables are substituted using values from ARGs and ENVs within the stage.

CMD

Syntax:

• CMD ["<arg>", "<arg>"...]
  • JSON format.
• CMD <cmd> [<arg> ...]
  • <cmd> and <arg>s must be separated by whitespace.
  • To include whitespace within an argument, the whitespace must be escaped using a backslash character or the argument must be surrounded in quotes.
  • Quotes to be included in an argument must be escaped with a backslash.
  • Any backslash characters present in an argument that don't precede whitespace or a quote will be passed through to the resulting string.

Variables are substituted using values from ARGs and ENVs within the stage.

COPY

Syntax:

• COPY [--chown=<user>:<group>] [--from=<name|index>] <src> ... <dest>
  • Arguments must be separated by whitespace.
• COPY [--chown=<user>:<group>] [--from=<name|index>] ["<src>",... "<dest>"] (this form is required for paths containing whitespace)
  • JSON format.

Variables are substituted using values from ARGs and ENVs within the stage.

ENTRYPOINT

Syntax:

• ENTRYPOINT ["<arg>", "<arg>"...]
  • JSON format.
• ENTRYPOINT <cmd> [<arg> ...]
  • <cmd> and <arg>s must be separated by whitespace. To include whitespace within a single argument, the whitespace must be escaped using a backslash character or the argument must be surrounded in quotes. Quotes within an argument must also be escaped with a backslash. Any backslash characters present in an argument that don't precede whitespace or a quote will be passed through to the resulting string.

Variables are substituted using values from ARGs and ENVs within the stage.

ENV

Syntax:

• ENV <key> <value>
  • Everything after the first space character after <key> is included in <value>.
• ENV <key>=<value> ...
  • <key>=<value> pairs must be separated by whitespace.
  • Valid <key> characters are: letters, digits, '-', '_', and '.'.
  • <value>s may contain any character, but to include whitespace it must be escaped using a backslash character or the argument must be surrounded in quotes.
  • Quotes to be included in a <value> must be escaped with a backslash.

EXPOSE

Syntax:

• EXPOSE <port>[/<protocol>] ...
  • Arguments must be separated by whitespace.

Variables are substituted using values from ARGs and ENVs within the stage.

FROM

Syntax:

• FROM <image> [AS <name>]

Variables are substituted using globally defined ARGs (those that appear before the first FROM directive).

LABEL

Syntax:

• LABEL <key>=<value> ...
  • <key>=<value> pairs must be separated by whitespace.
  • Valid <key> characters are: letters, digits, '-', '_', and '.'.
  • <value>s may contain any character, but to include whitespace it must be escaped using a backslash character or the argument must be surrounded in quotes.
  • Quotes to be included in a <value> must be escaped with a backslash.

Variables are substituted using values from ARGs and ENVs within the stage.

MAINTAINER

Syntax:

• MAINTAINER <maintainer>

Variables are not substituted.

RUN

Syntax:

• RUN ["<arg>", "<arg>"...]
  • JSON format.
• RUN <full_cmd>
  • <full_cmd> will be passed to shell via 'sh -c' as-is (after variable substitution).

Variables are substituted using values from ARGs and ENVs within the stage.

STOPSIGNAL

Syntax:

• STOPSIGNAL <signal>

Variables are not substituted.

USER

Syntax:

• USER <user>:[<group>]
  • Can be specified by user/group name or user/group ID.

Variables are substituted using values from ARGs and ENVs within the stage.

VOLUME

Syntax:

• VOLUME ["<volume>", "<volume>"...]
• VOLUME <volume> [<volume> ...]
  • Volumes must be separated by whitespace characters.

Variables are substituted using values from ARGs and ENVs within the stage.

WORKDIR

Syntax:

• WORKDIR <path>

Variables are substituted using values from ARGs and ENVs within the stage.

ARG

Syntax:

• ARG <name>[=<default_val>]

If after the first FROM directive, variables are substituted into the directive using values from ARGs and ENVs within the stage. Else, variables are only substituted using values from other ARG directives that appeared prior to this one.

Variables defined by ARG directives before the first FROM are used only by all FROM directives. Those defined within a stage are scoped to that stage only.

Documentation

Index

• type AddDirective
  • func AddDirectiveFixture(args, chown string, srcs []string, dst string) *AddDirective
• type ArgDirective
• type CmdDirective
  • func CmdDirectiveFixture(args string, cmd []string) *CmdDirective
• type CopyDirective
  • func CopyDirectiveFixture(args, chown, fromStage string, srcs []string, dst string) *CopyDirective
• type Directive
• type EntrypointDirective
  • func EntrypointDirectiveFixture(args string, entrypoint []string) *EntrypointDirective
• type EnvDirective
  • func EnvDirectiveFixture(args string, envs map[string]string) *EnvDirective
• type ExposeDirective
  • func ExposeDirectiveFixture(args string, ports []string) *ExposeDirective
• type FromDirective
  • func FromDirectiveFixture(args, image, alias string) *FromDirective
• type HealthcheckDirective
• type LabelDirective
  • func LabelDirectiveFixture(args string, labels map[string]string) *LabelDirective
• type MaintainerDirective
• type RunDirective
  • func RunCommitDirectiveFixture(args string, cmd string) *RunDirective
  • func RunDirectiveFixture(args string, cmd string) *RunDirective
• type Stage
  • func ParseFile(filecontents string, args map[string]string) ([]*Stage, error)
• type Stages
• type StopsignalDirective
• type UserDirective
  • func UserDirectiveFixture(args, user string) *UserDirective
• type VolumeDirective
  • func VolumeDirectiveFixture(args string, volumes []string) *VolumeDirective
• type WorkdirDirective
  • func WorkdirDirectiveFixture(args string, workdir string) *WorkdirDirective

Types

type AddDirective

type AddDirective struct {
	// contains filtered or unexported fields
}

AddDirective represents the "ADD" dockerfile command.

func AddDirectiveFixture

func AddDirectiveFixture(args, chown string, srcs []string, dst string) *AddDirective

AddDirectiveFixture returns an AddDirective for testing purposes.

type ArgDirective

type ArgDirective struct {
	Name        string
	DefaultVal  string
	ResolvedVal *string
	// contains filtered or unexported fields
}

ArgDirective represents the "ARG" dockerfile command.

type CmdDirective

type CmdDirective struct {
	Cmd []string
	// contains filtered or unexported fields
}

CmdDirective represents the "CMD" dockerfile command.

func CmdDirectiveFixture

func CmdDirectiveFixture(args string, cmd []string) *CmdDirective

CmdDirectiveFixture returns a CmdDirective for testing purposes.

type CopyDirective

type CopyDirective struct {
	FromStage string
	// contains filtered or unexported fields
}

CopyDirective represents the "COPY" dockerfile command.

func CopyDirectiveFixture

func CopyDirectiveFixture(args, chown, fromStage string, srcs []string, dst string) *CopyDirective

CopyDirectiveFixture returns a CopyDirective for testing purposes.

type Directive

type Directive interface {
	// contains filtered or unexported methods
}

Directive defines a directive parsed from a line from a Dockerfile.

type EntrypointDirective

type EntrypointDirective struct {
	Entrypoint []string
	// contains filtered or unexported fields
}

EntrypointDirective represents the "ENTRYPOINT" dockerfile command.

func EntrypointDirectiveFixture

func EntrypointDirectiveFixture(args string, entrypoint []string) *EntrypointDirective

EntrypointDirectiveFixture returns a EntrypointDirective for testing purposes.

type EnvDirective

type EnvDirective struct {
	Envs map[string]string
	// contains filtered or unexported fields
}

EnvDirective represents the "ENV" dockerfile command.

func EnvDirectiveFixture

func EnvDirectiveFixture(args string, envs map[string]string) *EnvDirective

EnvDirectiveFixture returns a EnvDirective for testing purposes.

type ExposeDirective

type ExposeDirective struct {
	Ports []string
	// contains filtered or unexported fields
}

ExposeDirective represents the "EXPOSE" dockerfile command.

func ExposeDirectiveFixture

func ExposeDirectiveFixture(args string, ports []string) *ExposeDirective

ExposeDirectiveFixture returns a ExposeDirective for testing purposes.

type FromDirective

type FromDirective struct {
	Image string
	Alias string
	// contains filtered or unexported fields
}

FromDirective represents the "FROM" dockerfile command.

func FromDirectiveFixture

func FromDirectiveFixture(args, image, alias string) *FromDirective

FromDirectiveFixture returns a FromDirective for testing purposes.

type HealthcheckDirective

type HealthcheckDirective struct {
	Interval    time.Duration
	Timeout     time.Duration
	StartPeriod time.Duration
	Retries     int

	Test []string
	// contains filtered or unexported fields
}

HeathcheckDirective represents the "LABEL" dockerfile command.

type LabelDirective

type LabelDirective struct {
	Labels map[string]string
	// contains filtered or unexported fields
}

LabelDirective represents the "LABEL" dockerfile command.

func LabelDirectiveFixture

func LabelDirectiveFixture(args string, labels map[string]string) *LabelDirective

LabelDirectiveFixture returns a LabelDirective for testing purposes.

type MaintainerDirective

type MaintainerDirective struct {
	Author string
	// contains filtered or unexported fields
}

MaintainerDirective represents the "MAINTAINER" dockerfile command.

type RunDirective

type RunDirective struct {
	Cmd string
	// contains filtered or unexported fields
}

RunDirective represents the "RUN" dockerfile command.

func RunCommitDirectiveFixture

func RunCommitDirectiveFixture(args string, cmd string) *RunDirective

RunCommitDirectiveFixture returns a RunDirective with a commit annotation for testing purposes.

func RunDirectiveFixture

func RunDirectiveFixture(args string, cmd string) *RunDirective

RunDirectiveFixture returns a RunDirective for testing purposes.

type Stage

type Stage struct {
	From       *FromDirective
	Directives []Directive
}

Stage represents a parsed dockerfile stage.

func ParseFile

func ParseFile(filecontents string, args map[string]string) ([]*Stage, error)

ParseFile parses dockerfile from given reader, returns a ParsedFile object.

type Stages

type Stages []*Stage

Stages is an alias for []*Stage.

type StopsignalDirective

type StopsignalDirective struct {
	Signal int
	// contains filtered or unexported fields
}

StopsignalDirective represents the "STOPSIGNAL" dockerfile command.

type UserDirective

type UserDirective struct {
	User string
	// contains filtered or unexported fields
}

UserDirective represents the "USER" dockerfile command.

func UserDirectiveFixture

func UserDirectiveFixture(args, user string) *UserDirective

UserDirectiveFixture returns a UserDirective for testing purposes.

type VolumeDirective

type VolumeDirective struct {
	Volumes []string
	// contains filtered or unexported fields
}

VolumeDirective represents the "VOLUME" dockerfile command.

func VolumeDirectiveFixture

func VolumeDirectiveFixture(args string, volumes []string) *VolumeDirective

VolumeDirectiveFixture returns a VolumeDirective for testing purposes.

type WorkdirDirective

type WorkdirDirective struct {
	WorkingDir string
	// contains filtered or unexported fields
}

WorkdirDirective represents the "WORKDIR" dockerfile command.

func WorkdirDirectiveFixture

func WorkdirDirectiveFixture(args string, workdir string) *WorkdirDirective

WorkdirDirectiveFixture returns a WorkdirDirective for testing purposes.