Dockerfile

A declarative setup file with steps of instructions for the Image.

By default an Image starts from a blank image, but most of the time you will start from another base image.

Syntax Example

Dockerfile

FROM image:lastest
RUN command
EXPOSE 8000

Working with multiple Dockerfiles

If necessary when creating multiple containers, you can create multiple Dockerfiles in the same folder like.

/dockerfiles
├── php.dockerfile
├── nginx.dockerfile
├── mysql.dockerfile
└── ...

Or one folder per Dockerfile.

/php
└── Dockerfile
/nginx
└── Dockerfile
/mysql
└── Dockerfile

Building the Image

docker build [OPTIONS] (Path | Url | -)

Ex.:

docker build -t "your-image-name" .

Flag	Description
--annotation	Add annotation to the image.
--build-arg	Overwrite or set ARG values.
-f or --file	The name of the Dockerfile. (default: PATH/Dockerfile)
--no-cache	Don't use cache when building the Image.
-o or --output	Output destination. (format: type=local,dest=path)
-t or --tag	Name and optionally a tag (format: name:tag)

Dockerfile Commands

Dockerfile referenceDocker Documentation

CLI commands

ARG

Set <varname>=<value> pairs that will be available:

• During ONLY at build stages.

• In Dockerfile as soon as you define them through ARG instructions.

Defines variables to be used ONLY at build-time. So they are accessable to the Dockerfile and docker build.

ARGs are useful for variables that should be used or changed at build-time, and that should not be persisted after the image was build.

ARG values can be inspected with docker history on an Image.

For this reason it is not recommended to use them for credentials, secrets or sensitive data, if untrusted users have access to the Image.

Forms
ARG <varname>=<value>

Not accessible at run-time, what it means in practice

This means that these variables are not accessible inside running containers.

But it also means that CMD and ENTRYPOINT instructions won't see these values by default.

Default <value>

You can define these variables without value, and expect the value inline at docker build. If not provided Docker will generate an error.

ARG USERNAME

You may also specify default values for these variables.

ARG USERNAME="user"

Access the ARG values within the Dockerfile

Access with $ or ${}.

ARG USERNAME="user"
USER $USERNAME
# OR
ARG VALUE="development"
RUN echo "The value is $VALUE"

# Using ARG to supply build only data for ENV
ARG NODE_ENV_VALUE="development"
ENV NODE_ENV=$NODE_ENV_VALUE

Overwriting <value>

You can overwrite values from an inline docker build --build-arg <varname>=<value>.

ADD

Copies new files or folders from the SOURCE and adds them to the filesystem of the image at DEST.

Allows you to copy files from remote URL, or GIT repositories. ADD is ideal for remote file copy.

Also if files are TAR files, they are automatically decompressed.

Forms	Description
ADD [OPTIONS] ...SOURCE DEST
ADD [OPTIONS] [...SOURCE, DEST]	Required for paths with whitespace.

If multiple source files are specified, the last argument must be a DEST, with a trailing /.

Trailing / at DEST

If the destination has a trailing /, the file or folder is copied inside this path.

If the destination doesn't have, the file or folder is copied beside the path.

DEST path

Destinations that begin with /, are considered absolute paths.

Destinations without / at the start, are considered relative to the working directory.

CMD

Run variable commands when running a container from an image.

• It doesn't run on build time, only specify intended commands for the image.

If more than one CMD is specified, ONLY the LAST one takes effect.

CMD can specify only params (The 2° form), if there is an ENTRYPOINT command specified before. Both CMD and ENTRYPOINT must be in Exec form.

Inline specified COMMAND on a docker run WILL overwrite the CMD of the Dockerfile.

Forms	Description
CMD ["executable","param1","param2"]	Exec form as Array.
CMD ["param1","param2"]	As default params for a previous ENTRYPOINT.
CMD command param1 param2	Shell form as string.

COPY

Copies new files or folders from the SOURCE and adds them to the filesystem of the image at DEST.

Forms	Description
COPY [OPTIONS] ...SOURCE DEST
COPY [OPTIONS] [...SOURCE, DEST]	Required for paths with whitespace.

If multiple source files are specified, the last argument must be a DEST, with a trailing /.

Trailing / at DEST

If the destination has a trailing /, the file or folder is copied inside this path.

If the destination doesn't have, the file or folder is copied beside the path.

DEST path

Destinations that begin with /, are considered absolute paths.

Destinations without / at the start, are considered relative to the working directory.

ENTRYPOINT

Run fixed commands when running a container from an image.

If more than one ENTRYPOINT is specified, ONLY the LAST one takes effect.

You may pass inline arguments to docker run "image-name" -d, that will be appended to the ENTRYPOINT arguments.

You can overwrite entirely an ENTRYPOINT with the --entrypoint flag docker run "image-name" --entrypoint.

Forms	Description
ENTRYPOINT ["executable","param1","param2"]	Exec form as Array.
ENTRYPOINT command param1 param2	Shell form as string.

EXPOSE

Informs Docker that the container listens on the specified network ports at runtime.

You may specify if the port is UDP or TCP(Default).

The EXPOSE instruction doesn't actually publish the port.

It functions as a type of documentation between the person who builds the image and the person who runs the container.

EXPOSE 80

ENV

Set <key>=<value> pairs that will be available:

• During build stages AND future running containers.

• In Dockerfile as soon as you define them through ENV instructions.

You can inspect Image ENV values with docker inspect "image-id".

It is not recommended to use them for credentials, secrets or sensitive data, if untrusted users have access to the Image.

These variable leave traces in the Docker Image.

Don't just place them at the top of the Dockerfile.

Their placement might impact the caching of layers when developing Images, if their values are constantly updated.

Forms
ENV <key>=<value> ...

String <value> can be in the form of

ENV MY_VAR="A string value"
# OR
ENV MY_VAR=A\ string \value

Access the ENV values within the Dockerfile

Access with $ or ${}.

ENV PORT=80
EXPOSE $PORT

Overwriting <value>

To overwrite values at build-time, you must use ARG to set the default value for ENV.

ARG NODE_ENV
ENV NODE_ENV=$NODE_ENV
ENTRYPOINT ["node", "app.js", "NODE_ENV=$NODE_ENV"]

You can overwrite values at run-time docker run "image-name" --env <key>=<value>.

.env File

Read ENV variables from a file by specifiyng it when running the container.

docker run "image-name" --env-file ./.env

RUN

Execute commands creating a new layer on top of the current image. (The added layer is used in the next step inside the Dockerfile)

Forms	Description
RUN [OPTIONS] [...COMMAND]	Exec form as Array.
RUN [OPTIONS] ...COMMAND	Shell form as string.

The cache for RUN instructions can be forcely invalidated by using --no-cache flag.

docker build --no-cache

USER

The USER instruction sets the user name (or UID) and optionally the user group (or GID) to use as the default user and group for the remainder of the current stage.

When the user doesn't have a primary group, then it will use as part of the root group.

The specified user is used for RUN instructions and at runtime, runs the relevant ENTRYPOINT and CMD commands.

Forms
USER <user>[:<group>]
USER <UID>[:GID]

WORKDIR

Sets the working directory for any RUN, CMD, ENTRYPOINT, COPY and ADD instructions that follow it in the Dockerfile.

If the specified WORKDIR doesn't exist, it will be created.

If multiple WORKDIR are defined, instructions will always use the last previous one for them.

Relative paths on multiple WORKDIR will add them up.

WORKDIR /path

VOLUME

Creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers.

Forms	Description
VOLUME /var/log	As string with multiple arguments.
VOLUME ["/var/log"]	As JSON Array. (Preferred way)