===== Overview =====

Summary of Dockerfiles.

External links:

  * [[https://takacsmark.com/dockerfile-tutorial-by-example-dockerfile-best-practices-2018/|https://takacsmark.com/dockerfile-tutorial-by-example-dockerfile-best-practices-2018/]]
  * [[https://docs.docker.com/engine/reference/builder/|https://docs.docker.com/engine/reference/builder/]]
  * [[https://www.docker.com/blog/intro-guide-to-dockerfile-best-practices/|https://www.docker.com/blog/intro-guide-to-dockerfile-best-practices/]]

===== Notes =====

  * ''podman'' also reads a ''Containerfile'' (also CPP-processed ''Containerfile.in'')
  * default context is current directory (".")
  * ''rm ~/.config/containers/libpod.conf''
  * ''.dockerignore'' file (podman variant?)

===== Q =====

  * Applicability of Containerfile? Also ".in" suffix for podman?
  * COPY versus ADD?
  * Does every new FROM directive start a new "build stage"?
  * What is the scope of an ENV versus ARG directive?
  * Can a context be a local tarball? Others?
  * How to use ''%%--%%cache-from''?
  * relevance of ''.dockerignore'' with ''podman''/''buildah''?
  * Can we display context?

===== Usage =====

Needs:

  * Dockerfile/Containerfile
  * context

<code>
$ docker build .
$ docker build dir/
$ docker build -f /path/to/Dockerfile .
$ docker build -t automatron .
$ docker build -t automatron https://github.com/madflojo/automatron.git
$ docker build -t automatron http://example.com/automatron.tar.gz
</code>
===== General concepts =====

==== Context ====

  * a context is processed recursively (keep it minimal)
  * each instruction is run independently, creating a new layer

==== Parser directives ====

  * escape
  * syntax (BuildKit only)

==== .dockerignore (in root dir of context) ====

  * You can safely exclude ''Dockerfile'' and ''.dockerignore''; they're sent, anyway.
  * Uses Go's filepath.Match rules
  * Also ''**/*.go'', and exceptions using ''!''
  * last match takes precedence

===== Dockerfile directives =====

==== ARG ====

  * only instruction that can precede FROM instructions
  * used only by subsequent FROM instructions

==== FROM ====

  * Dockerfile must start with a ''FROM'' instruction (after possible ''ARG'' directives)
  * sets a //base image//, initializes a new //build stage//
  * can occur multiple times in a Dockerfile, perhaps to make one build stage dependent on another

==== LABEL ====

<code>
$ docker inspect
</code>

==== ENV ====

Two forms:

<code>
ENV <key> <value>
ENV <key1>=<value1> <key2>=<value2> ...
</code>

Set on command line:

<code>
$ docker run --env <key>=<value> ...
</code>

==== RUN ====

Two forms:

  * shell (prefixed with ''/bin/sh -c'')
  * exec

Each RUN commits a new image, used in the next step.

To set environment for a single command:

<code>
RUN <key>=<value> <command>
</code>

==== COPY (preferred unless you need ADD extensions) ====

  * ''.dockerignore'' file, see [[https://docs.docker.com/engine/reference/builder/#dockerignore-file|here]]

==== ADD ====

''COPY'' is preferred, except for URLs and tarballs, etc, or if you're redirecting from STDIN where there is no build context; the Dockerfile at the root of the archive will be used as the build context.

==== CMD ====

  * can be only one in any Dockerfile (last takes precedence)

Types:

  * exec form (preferred)
  * shell form
  * default parms to ENTRYPOINT


==== ENTRYPOINT ====

  * exec form (preferred)
  * shell form

==== WORKDIR ====

==== USER ====

==== VOLUME ====

==== EXPOSE ====

  * does not actually publish ports, just advertises them
  * TCP if protocol is not specified
  * use ''docker run -p/-P'' to actually expose ports

==== HEALTHCHECK ====