Master Dockerfile: Essential Commands, Structure, and Best Practices

Overview

Dockerfile is a text file used to build Docker images; it contains a series of instructions and explanations required for image construction.

Official documentation:

https://docs.docker.com/engine/reference/builder/

Dockerfile examples:

https://github.com/dockerfile/

Dockerfile Structure

Dockerfile structure is mainly divided into four parts:

Base image information

Maintainer information

Image operation instructions

Container start‑up commands (CMD/ENTRYPOINT)

Note: Each line of a Dockerfile supports one instruction; an instruction may carry multiple parameters (supports &&). Comments starting with "#" are allowed (JSON files do not support # comments), but the four points above are not mandatory.

Common Dockerfile Instructions

ARG

– defines a variable used during image build; the only instruction that can appear before FROM. FROM – specifies the base image; only one or multiple ARG instructions may precede it. MAINTAINER (deprecated) – image maintainer name or email. VOLUME – defines a mount point for anonymous data volumes. RUN – executes a command inside the image, similar to a shell command. COPY – copies files from the host into the image. ADD – copies and extracts compressed files or remote URLs into the image. ENV – sets environment variables. WORKDIR – sets the working directory for subsequent instructions. USER – specifies the user (and optionally group) for following commands. EXPOSE – declares container service ports (default TCP). CMD – command executed when the container starts; only the last CMD takes effect. ENTRYPOINT – command that cannot be overridden by docker run arguments unless --entrypoint is used. HEALTHCHECK – defines a command to monitor container health. ONBUILD – registers instructions that will be executed only when the image is used as a base for a child build. LABEL – adds metadata key‑value pairs to the image, replacing MAINTAINER.

1) Image Build (docker build)

docker build -t text:v1 . --no-cache
# To tag the image to multiple repositories, add multiple -t parameters
docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest .

### Parameter explanation
# -t: specify image name
# . : current directory Dockerfile
# -f: specify Dockerfile path
# --no-cache: do not use cache

2) Run Container Test (docker run)

# Non‑interactive run
docker run centos:7.4.1708 /bin/echo "Hello world"

### Interactive execution
# -t: allocate a pseudo‑TTY
# -i: keep STDIN open
# -d: run in background (detached)

docker run -it centos:7.4.1708 /bin/bash
docker run -itd centos:7.4.1708 /bin/bash

### Enter container
# When using -d, the container runs in background; you can enter it with:

docker exec -it b2c0235dc53 /bin/bash
docker attach b2c0235dc53

3) ARG

Build‑time variables, similar to ENV but only available during docker build . They cannot be seen inside the final image. Only one ARG can be defined before FROM . Use docker build --build-arg name=value to override.

Syntax:

ARG <parameter_name>[=<default_value>]

Example:

# Define ARG before FROM, effective only in FROM
ARG VERSION=latest
FROM centos:${VERSION}
# Redefine after FROM (no value needed)
ARG VERSION
RUN echo $VERSION >/tmp/image_version

4) FROM

All custom images are based on a FROM image – required.

Syntax:

FROM [--platform=<platform>] <image> [AS <name>]
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]

If building multi‑platform images, you can use --platform to specify the target platform (e.g., linux/amd64, linux/arm64, windows/amd64). The default is the platform of the build request. Global build args can be used for the flag value, e.g., --platform=$BUILDPLATFORM .

Example:

ARG VERSION=latest
FROM busybox:${VERSION}
# FROM --platform="linux/amd64" busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version

5) MAINTAINER (deprecated)

Image maintainer name or email address.

Syntax:

MAINTAINER <name>

Example:

LABEL org.opencontainers.image.authors="[email protected]"

6) VOLUME

Defines an anonymous data volume; if you forget to mount a volume when starting a container, Docker will create an anonymous one.

Purpose:

Avoid data loss on container restart.

Prevent containers from growing indefinitely.

Use -v with docker run to specify host mount points.

Syntax:

# Path after VOLUME is the container path; host path is generated automatically
VOLUME ["<path1>", "<path2>"]
VOLUME <path>

Example:

FROM ubuntu
RUN mkdir /myvol
RUN echo "hello world" > /myvol/greeting
VOLUME /myvol

7) RUN

Executes the following command line inside the image.

Syntax:

Shell form (default shell is /bin/sh -c on Linux or cmd /S /C on Windows):

RUN <command>

Exec form:

RUN ["executable", "param1", "param2"]

Example (three equivalent forms):

# All three are equivalent
RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'
RUN /bin/bash -c "source $HOME/.bashrc; echo $HOME"
RUN ["/bin/bash", "-c", "source $HOME/.bashrc; echo $HOME"]

8) COPY

Copies files or directories from the host into the image. Unlike ADD , it does not download or extract archives. New files are created with UID/GID 0 unless --chown is used.

Syntax:

COPY [--chown=<user>:<group>] <src>... <dest>
COPY [--chown=<user>:<group>] ["<src>", ... "<dest>"]

Examples:

# Copy all files starting with "hom"
COPY hom* /mydir/
# Single‑character wildcard
COPY hom?.txt /mydir/
# Relative path
COPY test.txt relativeDir/
# Absolute path
COPY test.txt /absoluteDir/
# Change ownership
COPY --chown=55:mygroup files* /somedir/
COPY --chown=bin files* /somedir/
COPY --chown=1 files* /somedir/
COPY --chown=10:11 files* /somedir/

9) ADD

Copies files or directories into the image; if the source is a URL or a compressed archive, it will be downloaded or extracted automatically.

Differences from COPY:

Advantages : automatically extracts tar archives (gzip, bzip2, xz).

Disadvantages : cannot copy tar archives without extracting; may invalidate build cache and slow down builds.

Syntax:

ADD [--chown=<user>:<group>] <src>... <dest>
ADD [--chown=<user>:<group>] ["<src>", ... "<dest>"]

Examples:

# Wildcard
ADD hom* /mydir/
# Relative path
ADD test.txt relativeDir/
# Absolute path
ADD test.txt /absoluteDir/
# Change ownership
ADD --chown=55:mygroup files* /somedir/
ADD --chown=bin files* /somedir/
ADD --chown=1 files* /somedir/
ADD --chown=10:11 files* /somedir/

When to use:

Use ADD only when you need remote URLs or automatic extraction.

Prefer COPY for all other cases, especially when copying from other build stages.

10) ENV

Sets environment variables that persist in later instructions and at container runtime.

Syntax:

ENV <key1>=<value1> <key2>=<value2> ...
# The "=" syntax cannot set multiple variables in a single instruction without confusion.
ENV <key> <value>

Examples:

ENV JAVA_HOME=/usr/local/jdk
ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \
    MY_CAT=fluffy
ENV JAVA_HOME /usr/local/jdk

11) WORKDIR

Sets the working directory for subsequent instructions; the directory must exist in each layer.

Syntax:

WORKDIR <directory_path>

Example:

FROM busybox
ENV FOO=/bar
WORKDIR ${FOO}   # WORKDIR /bar

12) USER

Specifies the user (and optionally group) for following commands; the user/group must already exist.

Syntax:

USER <username>[:<group>]
USER <UID>[:<GID>]

Example:

FROM busybox
RUN groupadd --system --gid=9999 admin && useradd --system --home-dir /home/admin --uid=9999 --gid=admin admin
USER admin:admin
# USER 9999:9999

13) EXPOSE

Declares a port that the container listens on; it is only a declaration.

Purpose:

Helps image users understand which ports the service uses.

When using docker run -P, Docker will randomly map the declared ports.

Syntax:

# Default protocol is TCP
EXPOSE <port> [<port>/<protocol>...]

Examples:

EXPOSE 80/TCP 443/TCP
EXPOSE 80 443
EXPOSE 80/tcp
EXPOSE 80/udp

14) CMD

Runs a command when the container starts; unlike RUN , it is not executed during image build. Only the last CMD takes effect.

Syntax:

CMD <shell command>
CMD ["<executable>", "<param1>", "<param2>"]
CMD ["<param1>", "<param2>"]   # Provides default arguments to ENTRYPOINT

It is recommended to use the JSON array form for clarity; the shell form is internally converted to the array form with /bin/sh as the executable.

Examples:

CMD cat /etc/profile
CMD ["/bin/sh", "-c", "/etc/profile"]

Note: If multiple CMD instructions exist, only the last one is effective.

15) ENTRYPOINT

Similar to CMD but cannot be overridden by command‑line arguments unless --entrypoint is used; arguments supplied to docker run are passed as parameters to the ENTRYPOINT program.

Syntax:

# Exec form (preferred)
ENTRYPOINT ["executable", "param1", "param2"]
# Shell form
ENTRYPOINT command param1 param2

Examples:

FROM ubuntu
ENTRYPOINT ["top", "-b"]
# CMD as arguments to ENTRYPOINT
CMD ["-c"]
# Equivalent to:
ENTRYPOINT ["top", "-b -c"]
ENTRYPOINT top -b -c

Note: If multiple ENTRYPOINT instructions exist, only the last one is effective.

16) HEALTHCHECK

Specifies a command to monitor the health of a container.

Syntax:

HEALTHCHECK [OPTIONS] CMD <command>
HEALTHCHECK NONE   # Disable inherited health checks

Options for CMD: --interval=DURATION (default 30s): interval between checks. --timeout=DURATION (default 30s): timeout for each check. --start-period=DURATION (default 0s): initialization period before failures are counted. --retries=N (default 3): number of retries before marking unhealthy.

Exit status meanings:

0 – healthy.

1 – unhealthy.

2 – reserved (do not use).

Example:

FROM nginx
MAINTAINER Securitit
HEALTHCHECK --interval=5s --timeout=3s \
  CMD curl -f http://localhost/ || exit 1
CMD ["usr/sbin/nginx", "-g", "daemon off;"]

17) ONBUILD

ONBUILD registers a trigger instruction (e.g., RUN , COPY ) that will be executed only when the current image is used as a base for a child build.

Syntax:

ONBUILD <other_instruction>

Example:

FROM node:slim
RUN mkdir /app
WORKDIR /app
ONBUILD COPY ./package.json /app
ONBUILD RUN ["npm", "install"]
ONBUILD COPY . /app/
CMD ["npm", "start"]

18) LABEL

Adds metadata to the image as key‑value pairs, replacing the deprecated MAINTAINER instruction.

Syntax:

LABEL <key>=<value> <key>=<value> ...

Example (add author information):

LABEL org.opencontainers.image.authors="runoob"

Difference Between ARG and ENV

ARG variables exist only during the image build process; they are not present in the running container.

ENV variables persist in the container after it starts.

CMD, ENTRYPOINT, command, args Scenario Tests

When a Kubernetes yaml file defines both command and args, they override the Dockerfile defaults. The following four cases describe the behavior.

1) Neither command nor args are defined

If both are omitted, Docker uses the defaults from the Dockerfile.

FROM centos
COPY test.sh /
RUN chmod +x /test.sh
ENTRYPOINT ["/test.sh", "ENTRYPOINT"]
CMD ["CMD"]

2) command defined, args not defined

Docker ignores the default CMD and runs only the command from the yaml.

# yaml snippet (command only)
command: ['/test.sh']
# args omitted

3) command not defined, args defined

Docker runs the ENTRYPOINT from the Dockerfile, passing the yaml args as parameters; CMD is ignored.

# yaml snippet (args only)
args: ['args']

4) Both command and args defined

Docker completely overrides the Dockerfile defaults and uses the yaml command and args .

# yaml snippet (command and args)
command: ['/test.sh', 'command']
args: ['args']

The Dockerfile tutorial ends here. Feel free to leave comments if you have questions!