Copyright notice: This is an original article by xwi88, licensed under CC BY-NC 4.0. Commercial use is prohibited; please cite the source when reposting. Follow at https://github.com/xwi88

• Docker version: Docker version 20.10.12, build e91ed57
• Compose version: Docker Compose version 2.2.2

Docker reference resources

File formats

Command-line interfaces (CLIs)

Application programming interfaces (APIs)

Drivers & specs

Docker CLI usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Options:
      --config string      Location of client config files (default "/Users/wangxin/.docker")
  -c, --context string     Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use")
  -D, --debug              Enable debug mode
  -H, --host list          Daemon socket(s) to connect to
  -l, --log-level string   Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
      --tls                Use TLS; implied by --tlsverify
      --tlscacert string   Trust certs signed only by this CA (default "/Users/wangxin/.docker/ca.pem")
      --tlscert string     Path to TLS certificate file (default "/Users/wangxin/.docker/cert.pem")
      --tlskey string      Path to TLS key file (default "/Users/wangxin/.docker/key.pem")
      --tlsverify          Use TLS and verify the remote
  -v, --version            Print version information and quit

Management Commands:
  builder     Manage builds
  buildx*     Docker Buildx (Docker Inc., v0.7.1)
  compose*    Docker Compose (Docker Inc., 2.2.2)
  config      Manage Docker configs
  container   Manage containers
  context     Manage contexts
  image       Manage images
  manifest    Manage Docker image manifests and manifest lists
  network     Manage networks
  node        Manage Swarm nodes
  plugin      Manage plugins
  scan*       Docker Scan (Docker Inc., v0.17.0)
  secret      Manage Docker secrets
  service     Manage services
  stack       Manage Docker stacks
  swarm       Manage Swarm
  system      Manage Docker
  trust       Manage trust on Docker images
  volume      Manage volumes

Commands:
  attach      Attach local standard input, output, and error streams to a running container
  build       Build an image from a Dockerfile
  commit      Create a new image from a container's changes
  cp          Copy files/folders between a container and the local filesystem
  create      Create a new container
  diff        Inspect changes to files or directories on a container's filesystem
  events      Get real time events from the server
  exec        Run a command in a running container
  export      Export a container's filesystem as a tar archive
  history     Show the history of an image
  images      List images
  import      Import the contents from a tarball to create a filesystem image
  info        Display system-wide information
  inspect     Return low-level information on Docker objects
  kill        Kill one or more running containers
  load        Load an image from a tar archive or STDIN
  login       Log in to a Docker registry
  logout      Log out from a Docker registry
  logs        Fetch the logs of a container
  pause       Pause all processes within one or more containers
  port        List port mappings or a specific mapping for the container
  ps          List containers
  pull        Pull an image or a repository from a registry
  push        Push an image or a repository to a registry
  rename      Rename a container
  restart     Restart one or more containers
  rm          Remove one or more containers
  rmi         Remove one or more images
  run         Run a command in a new container
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  search      Search the Docker Hub for images
  start       Start one or more stopped containers
  stats       Display a live stream of container(s) resource usage statistics
  stop        Stop one or more running containers
  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
  top         Display the running processes of a container
  unpause     Unpause all processes within one or more containers
  update      Update configuration of one or more containers
  version     Show the Docker version information
  wait        Block until one or more containers stop, then print their exit codes

Run 'docker COMMAND --help' for more information on a command.

To get more help with docker, check out our guides at https://docs.docker.com/go/guides/

Docker Compose CLI usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

Usage:  docker compose [OPTIONS] COMMAND

Docker Compose

Options:
      --ansi string                Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
      --compatibility              Run compose in backward compatibility mode
      --env-file string            Specify an alternate environment file.
  -f, --file stringArray           Compose configuration files
      --profile stringArray        Specify a profile to enable
      --project-directory string   Specify an alternate working directory
                                   (default: the path of the Compose file)
  -p, --project-name string        Project name

Commands:
  build       Build or rebuild services
  convert     Converts the compose file to platform's canonical format
  cp          Copy files/folders between a service container and the local filesystem
  create      Creates containers for a service.
  down        Stop and remove containers, networks
  events      Receive real time events from containers.
  exec        Execute a command in a running container.
  images      List images used by the created containers
  kill        Force stop service containers.
  logs        View output from containers
  ls          List running compose projects
  pause       Pause services
  port        Print the public port for a port binding.
  ps          List containers
  pull        Pull service images
  push        Push service images
  restart     Restart containers
  rm          Removes stopped service containers
  run         Run a one-off command on a service.
  start       Start services
  stop        Stop services
  top         Display the running processes
  unpause     Unpause services
  up          Create and start containers
  version     Show the Docker Compose version information

Run 'docker compose COMMAND --help' for more information on a command.

Docker commands

Common management commands

• docker context [--help] context management
• docker compose [--help] docker compose commands v2.2.2+
• docker container [--help] container commands
• docker image [--help] image commands
  • docker image prune remove untagged (<none>) images and images not used by any container
• docker volume [--help] volume (directory mount) commands
• docker network [--help] network commands
• docker system [--help] system commands
  • docker system df show disk usage
  • docker system info == docker info Display system-wide information
• docker scan [--help] scan and analyze images
• docker manifest [--help] view image manifests; experimental

Common commands

• docker build [--help] build an image
  • docker build [[-t tag] ...] -f [PATH/Dockerfile] .
  • docker build -t tag1 -t tag2 -f [PATH/Dockerfile] . build multiple tags at once
• docker commit [OPTIONS] <container> <REPOSITORY[:TAG]> create an image from a container
• docker cp copy files between a container and the local filesystem
  • docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-
  • docker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH
• docker create [OPTIONS] IMAGE [COMMAND] [ARG...] — usually you just use docker run to create and run
• docker history = docker image history view image history
• docker images list images
• docker login
• docker search
• docker tag
• docker pull
• docker build
• docker run
• docker push
• docker stop
• docker logs

docker image filtering

docker images -f [filter params]

• dangling=(true|false) none-tag images
• label=<key> or label=<key>=<value> filter by label
• before=(<image-name>[:tag]|<image-id>|<image@digest>)
• since=(<image-name>[:tag]|<image-id>|<image@digest>)
• reference=(pattern of an image reference)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

docker images -f dangling=true
docker images -f label=author
docker images -f label=author=xwi88
docker images -f reference="v8fg/*"
docker images -f reference="v8fg/alpine"
docker images -f reference="v8fg/alpine:*"
docker images -f reference="v8fg/golang:1.18*"
docker images -f reference="v8fg/golang:*1.18*"
docker images -f reference="[REPOSITORY:TAG]"
docker images -f reference="tes*"
docker images -f reference="test"
docker images -f reference="test*2"

docker commit — create an image from a container

docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]

1
2
3
4
5
6
7
8
9

Usage:  docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]

Create a new image from a container's changes

Options:
  -a, --author string    Author (e.g., "John Hannibal Smith <hannibal@a-team.com>")
  -c, --change list      Apply Dockerfile instruction to the created image
  -m, --message string   Commit message
  -p, --pause            Pause container during commit (default true)

prune — one-shot cleanup of images, containers, etc.

• docker image prune -a remove all images not used by any container
• docker container prune remove all stopped containers
• docker volume prune remove all unmounted volumes
• docker system prune remove all docker resources
• docker network prune remove all networks

Simple Cheat Sheet

• demo images: v8fg/demo
• demo image: v8fg/demo[:latest]
• demo container name: v8fg-demo

Running Containers

1
2
3
4
5
6

CONTAINER ID   IMAGE       COMMAND     CREATED              STATUS                          PORTS     NAMES
01430cc7b2c0   v8fg/demo   "/bin/sh"   11 seconds ago       Up 11 seconds                             v8fg-demo
83ce7dee0346   v8fg/demo   "/bin/sh"   About a minute ago   Created                                   thirsty_bassi
1bd61cc802f1   v8fg/demo   "/bin/sh"   About a minute ago   Up About a minute                         relaxed_beaver
be104825d061   v8fg/demo   "/bin/sh"   About a minute ago   Exited (0) About a minute ago             flamboyant_beaver
8cfe1c19773f   v8fg/demo   "bash"      About a minute ago   Exited (0) About a minute ago             flamboyant_euclid

Container Lifecycle Stuff

Resource Limits and Controls

Stats, Logs, and Events

Docker Images

Export/Import/Save/Load

• export, import: drops layer history; smaller — for base images, stripping history
• save, load: keeps layer history; larger

Docker Hub/Registry

Building Docker Images From A Dockerfile

Simple Dockerfile Example

v8fg/demo:latest

1
2
3
4
5

ARG FROM_REPOSITORY=alpine FROM_TAG=3.15.1
FROM ${FROM_REPOSITORY}:${FROM_TAG}
LABEL author=xwi88 type=demo name=latest github="https://github.com/xwi88" group="https://github.com/v8fg"
RUN apk add --no-cache tzdata bash
ENV TZ=Asia/Shanghai

v8fg/demo:ubuntu

1
2
3
4

FROM ubuntu
LABEL author=xwi88 type=demo name=ubuntu github="https://github.com/xwi88" group="https://github.com/v8fg"
RUN apt-get update && apt-get install nginx -y && apt-get clean && apt-get autoclean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
CMD ["/usr/sbin/nginx"]

Big Dockerfile Example

Volumes/Storage

Expose Ports

Networks

References

• docker run reference
• compose reference
• docker-cheat-sheet

Copyright notice: This is an original article by xwi88, licensed under CC BY-NC 4.0. Commercial use is prohibited; please cite the source when reposting. Follow at https://github.com/xwi88

Dockerfile overview

A Dockerfile is a text file used to build an image, made up of the instructions (instruction) and notes needed to build it. Each instruction builds one layer.

By default docker build . looks for a file named Dockerfile in the current directory; you can also pass a path and filename: docker build -f xxx/path/DockerfileName .

.dockerignore

Basic structure

Lines starting with # are comments and may appear anywhere; avoid extra spaces before #.

• Base image info
• Maintainer info
• Image-operation instructions
• Container-startup instruction

All instructions

• FROM
• RUN
• CMD
• LABEL
• EXPOSE
• ENV
• ADD
• COPY
• ENTRYPOINT
• VOLUME
• USER
• WORKDIR
• ARG
• ONBUILD
• STOPSIGNAL
• HEALTHCHECK
• SHELL

FROM

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

The FROM instruction initializes a new build stage and sets the base image for subsequent instructions. Therefore a valid Dockerfile must start with a FROM instruction.

• ARG is the only instruction that may appear before FROM.
• FROM may appear multiple times in a single Dockerfile to create multiple images or to use one build stage as a dependency of another. Just record the last image ID committed before each new FROM. Each FROM clears any state created by previous instructions.
• Adding AS <name> to FROM names the new build stage. You can reference it in later FROM and COPY --from=<name> instructions.
• tag and digest are optional. If omitted, the builder defaults to the latest tag. If the builder can’t find the tag, it errors.
• --platform=<platform> specifies which platform’s image FROM refers to, e.g. linux/amd64, linux/arm64, windows/amd64. It defaults to the target platform of the build request. You can use global build args in this flag, e.g. automatic platform args in the global scope, letting you force the build stage’s native platform (--platform=$BUILDPLATFORM) and cross-compile to the target within it.

ARG & FROM interaction

Variables declared by ARG may appear before the first FROM.

1
2
3
4
5
6
7
8

# FROM instructions support variables that are declared by any ARG instructions that occur before the first FROM.

ARG CODE_VERSION=latest
FROM base:${CODE_VERSION}
CMD  /code/run-app

FROM extras:${CODE_VERSION}
CMD  /code/run-extras

ARG scope

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# VERSION outside of a build stage, can`t be used in any instruction after a FROM
ARG VERSION=latest
FROM busybox:$VERSION

# To use the default value of an ARG declared before the first FROM use an ARG instruction without a value inside of a build stage
ARG VERSION
RUN echo $VERSION > image_version

ARG VERSION=old
# guess what? old
RUN echo $VERSION > image_version

ARG VERSION
# guess what? latest, again use ARG VERSION without value will override the before $VERSION
RUN echo $VERSION > image_version

RUN

• RUN <command> (shell form; default on linux: /bin/sh -c, on Windows: cmd /S /C)
• RUN ["executable", "param1", "param2"] (exec form)

RUN runs any command on top of the current image in a new layer and commits the result. The committed image is used for the next step in the Dockerfile.

The exec form avoids shell-string munging and lets you run commands in a base image that doesn’t contain a shell.

• Use the SHELL command to change the default shell
• Use a \ backslash to span a single RUN across lines for long commands

Replacing the default shell

1
2
3
4
5

RUN /bin/bash -c 'source $HOME/.bashrc; \
echo $HOME'

# equivalent to
RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'

1
2
3

# To use a different shell, other than '/bin/sh', use the exec form passing in the desired shell. For example:

RUN ["/bin/bash", "-c", "echo hello"]

RUN cache

• The RUN cache is not invalidated automatically on the next build
• A command like RUN apt-get dist-upgrade -y has its cache reused on the next build
• --no-cache invalidates the RUN cache: docker build --no-cache
• ADD and COPY can invalidate the RUN cache

CMD

• CMD ["executable","param1","param2"] (exec form, this is the preferred form)
• CMD ["param1","param2"] (as default parameters to ENTRYPOINT)
• CMD command param1 param2 (shell form)

Notes

• A Dockerfile may have only one CMD; if there are several, only the last takes effect.
• CMD’s main purpose is to provide defaults for an executing container. The defaults may include an executable, or omit it — in which case you must also specify ENTRYPOINT.
• If you use CMD to provide default args to ENTRYPOINT, both should use the JSON-array form.
• If you want the container to run the same executable every time, combine ENTRYPOINT and CMD
• If the user passes arguments to docker run, they override the CMD defaults
• Don’t confuse RUN with CMD. RUN actually runs a command and commits the result; CMD does nothing at build time but specifies the intended command for the image.

LABEL

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

1
2
3
4
5
6

LABEL multi.label1="value1" multi.label2="value2" other="value3"

# equivalent
LABEL multi.label1="value1" \
      multi.label2="value2" \
      other="value3"

View image labels: docker image inspect --format='' <image_id | image_name>

EXPOSE

EXPOSE <port> [<port>/<protocol>...]

EXPOSE tells Docker the container listens on the specified network ports at runtime. You can specify TCP or UDP; if no protocol is given, TCP is the default.

EXPOSE does not actually publish the port. It’s documentation between the person building the image and the person running the container about which ports to publish. To actually publish at runtime, use -p on docker run to publish and map one or more ports, or -P to publish all exposed ports to high ports.

By default EXPOSE assumes TCP. You can also specify UDP:

1
2
3
4
5
6

# expose udp
EXPOSE 80/udp

# expose both: tcp and udp
EXPOSE 80/tcp
EXPOSE 80/udp

expose for run

• P Publish all exposed ports to the host interfaces

• p=[] Publish a container’s port or a range of ports to the host

• docker run -p 80:80/tcp -p 80:80/udp ...

• docker run -p 80-81:80-81/tcp

ENV

ENV <key>=<value> ...

1
2

ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \
    MY_CAT=fluffy

• Takes effect during the build stage; can be overridden
• The value is in the environment of all subsequent instructions in the build stage and can be substituted inline. Substitution uses the same value for each variable across the whole instruction.
• Values set by ENV are persisted into the output image.
  • Viewable via docker inspect
  • Overridable at run time: docker run --env <key>=<value>
• Side effect: env vars you set may affect later build behavior — use carefully.
  • Use RUN <key>=<value> [<command>] to scope a value to a single instruction
  • Use ARG for build-time values that are not persisted into the image

1
2
3

ENV abc=hello # hello
ENV abc=bye def=$abc # abc=bye, def=hello;
ENV ghi=$abc # ghi=bye

ADD

• ADD [--chown=<user>:<group>] <src>... <dest>
• ADD [--chown=<user>:<group>] ["<src>",... "<dest>"] required when paths contain spaces

Notes

• --chown applies only to Linux containers
  • needs /etc/passwd / /etc/group to resolve user, group
• Copies from sources that may be files, directories, or remote URLs
  • Copies from outside into the image being built
  • src supports multiple sources into one target
  • src may contain wildcards (regex matching)
• dest may be absolute or relative to WORKDIR

1
2
3
4

ADD --chown=55:mygroup files* /somedir/
ADD --chown=bin files* /somedir/
ADD --chown=1 files* /somedir/
ADD --chown=10:11 files* /somedir/

COPY

• COPY [--chown=<user>:<group>] <src>... <dest>
• COPY [--chown=<user>:<group>] ["<src>",... "<dest>"] required when paths contain spaces

Notes

• --chown applies only to Linux containers
  • needs /etc/passwd / /etc/group to resolve user, group
• Copies from sources that may be files or directories
  • Copies from outside into the image being built
  • src supports multiple sources into one target
  • src may contain wildcards (regex matching)
  • Unlike ADD, URLs are not supported
• dest may be absolute or relative to WORKDIR

1
2
3
4

ADD --chown=55:mygroup files* /somedir/
ADD --chown=bin files* /somedir/
ADD --chown=1 files* /somedir/
ADD --chown=10:11 files* /somedir/

ENTRYPOINT

• ENTRYPOINT ["executable", "param1", "param2"] exec form recommended
• ENTRYPOINT command param1 param2 shell form cannot accept args passed via CLI, CMD, or run

Notes

• ENTRYPOINT lets you configure the container as an executable
• Only the last ENTRYPOINT takes effect
• docker run <image> args are appended to the exec-form ENTRYPOINT and override CMD args, so you can pass args to ENTRYPOINT from the CLI
• Override with docker run --entrypoint
• The exec form does not invoke a shell; if you need one, specify sh -c in ENTRYPOINT, e.g. ENTRYPOINT [ "sh", "-c", "echo $HOME" ]
• The shell form runs as a subcommand of /bin/sh -c and doesn’t pass signals. The executable won’t be PID 1 and won’t receive Unix signals, so it won’t receive SIGTERM from docker stop <container>

exec form ENTRYPOINT example

Exec form ENTRYPOINT example*

1
2
3

FROM ubuntu
ENTRYPOINT ["top", "-b"]
CMD ["-c"]

1
2
3
4
5
6
7
8

top - 16:04:58 up  8:38,  0 users,  load average: 0.25, 0.10, 0.04
Threads:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
%Cpu(s): 33.3 us, 33.3 sy,  0.0 ni, 33.3 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :   4180.6 total,    560.5 free,    326.4 used,   3293.7 buff/cache
MiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   3242.2 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    1 root      20   0    5972   3136   2712 R   0.0   0.1   0:00.03 top

1
2
3

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  3.0  0.0   5972  3216 pts/0    Ss+  16:05   0:00 top -b -H
root         8  0.0  0.0   5900  2920 pts/1    Rs+  16:05   0:00 ps aux

1
2

test
        0.35 real         0.14 user         0.07 sys

shell form ENTRYPOINT example

Shell form ENTRYPOINT example

shell form with exec

1
2

FROM ubuntu
ENTRYPOINT exec top -b

1
2
3
4
5
6
7
8

top - 16:37:19 up  9:10,  0 users,  load average: 0.20, 0.08, 0.02
Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
%Cpu(s): 20.0 us, 40.0 sy,  0.0 ni, 20.0 id, 20.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :   4180.6 total,    560.9 free,    323.7 used,   3296.0 buff/cache
MiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   3244.9 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    1 root      20   0    5972   3236   2812 R   0.0   0.1   0:00.04 top

1
2
3

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  1.0  0.0   5972  3200 pts/0    Ss+  16:55   0:00 top -b
root         8  0.0  0.0   5900  2924 pts/1    Rs+  16:55   0:00 ps aux

1
2

test
        0.35 real         0.15 user         0.08 sys

shell form (no exec)

1
2
3

FROM ubuntu
ENTRYPOINT top -b
CMD "param_inner"

1
2
3
4
5
6
7
8
9

top - 16:34:25 up  9:08,  0 users,  load average: 0.06, 0.06, 0.02
Tasks:   2 total,   1 running,   1 sleeping,   0 stopped,   0 zombie
%Cpu(s): 50.0 us, 50.0 sy,  0.0 ni,  0.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :   4180.6 total,    560.9 free,    324.3 used,   3295.4 buff/cache
MiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   3244.4 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    1 root      20   0    2616    592    528 S   0.0   0.0   0:00.03 sh
    8 root      20   0    5972   3188   2772 R   0.0   0.1   0:00.00 top

1
2
3
4

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.3  0.0   2616   600 pts/0    Ss+  16:46   0:00 /bin/sh -c top
root         7  0.0  0.0   5972  3128 pts/0    S+   16:46   0:00 top -b
root        24  0.0  0.0   5900  2836 pts/1    Rs+  16:46   0:00 ps aux

1
2

test
       10.33 real         0.13 user         0.07 sys

CMD and ENTRYPOINT interaction

Both define the command to run when the container starts.

• A Dockerfile must have at least one CMD or ENTRYPOINT
• ENTRYPOINT when using the container as an executable
• CMD should be the way to define default parameters for the ENTRYPOINT command, or a transient command to run in the container
• When the container is run with other args, CMD is overridden

CMD and ENTRYPOINT interaction rules

If the base image defines a CMD, setting ENTRYPOINT resets CMD to empty.

VOLUME

• VOLUME ["/data"]

The VOLUME instruction creates a mount point with the specified name and marks it as holding externally-mounted volumes from the host or other containers. The value may be a JSON array, VOLUME [”/var/log/”], or a plain string with multiple args, e.g. VOLUME /var/log or VOLUME /var/log /var/db.

See Share Directories via Volumes

1
2
3
4

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

1
2

root@abef26d10e25:/# ll myvol/*
-rw-r--r-- 1 root root 12 Mar 18 17:21 myvol/greeting

• Changing a volume from the Dockerfile: if any build step changes data in a volume after it’s declared, those changes are discarded.
  • Declare volumes at the end of the file!
• JSON formatting: the list is parsed as a JSON array. You must use double-quotes (") not single-quotes (').
• Host directories at runtime: host directories (mount points) are inherently host-dependent. This keeps images portable, since a given host directory isn’t guaranteed on every host. For this reason you cannot mount a host directory from the Dockerfile. VOLUME does not support a host-dir argument. You must specify the mount point when creating/running the container.

USER

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

USER sets the username (or UID) and optional group (or GID) to use when running the image, and for any RUN, CMD, and ENTRYPOINT that follow it in the Dockerfile.

When you specify a group for the user, the user has only that group’s membership. Any other configured group memberships are ignored.

WORKDIR

• WORKDIR /path/to/workdir

• Sets the working directory for any RUN, CMD, ENTRYPOINT, COPY, and ADD that follow it. If WORKDIR doesn’t exist, it’s created — even if it’s not used in any later instruction.

• WORKDIR can be used multiple times. A relative path is relative to the previous WORKDIR.

• WORKDIR resolves ENV variables set before it

• If unset, WORKDIR defaults to /

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd
# output /a/b/c

ENV DIRPATH=/path
WORKDIR $DIRPATH/$DIRNAME
RUN pwd
# output /path/$DIRNAME

ARG

• ARG <name>[=<default value>]

• ARG defines a variable users can pass at build time with the --build-arg <varname>=<value> flag of docker build. If a user passes a build arg not defined in the Dockerfile, the build prints a warning.

• Don’t use build-time variables to pass secrets like github keys or user credentials. With docker history, build-time values are visible to anyone with the image.

1
2
3
4

FROM busybox
ARG user1
ARG buildno
# ...

Default values

1
2
3
4

FROM busybox
ARG user1=someuser
ARG buildno=1
# ..

Scope

• An ARG variable is in effect from the line it’s declared on, downward in the Dockerfile; nowhere else.
• docker build --build-arg <name>=<value> overrides <arg-name>
• An ARG goes out of scope at the end of the build stage that declares it. To use an ARG across stages, each stage must declare it.
  • Each FROM starts a build stage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

FROM busybox
USER ${user:-some_user}
ARG user
USER $user
# ...

# -------multi build stage 1 -----------
FROM busybox
ARG SETTINGS # declare it to use next
RUN ./run/setup $SETTINGS

# -------multi build stage 2 -----------
FROM busybox
ARG SETTINGS  # declare it to use next
RUN ./run/other $SETTINGS

Using ARG variables

• For the same-named ARG and ENV, an ENV defined after the ARG overrides the nearest preceding ARG value.
• ARG VAR_NAME may be repeated; each acts as a reset and can be overridden by the nearest following same-named ENV.
• Avoid:
  • declaring ARG VAR_NAME multiple times
  • using the same name for an ARG and an ENV
  • naming a variable the same as a system one, unless you mean to

1
2
3
4

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=v1.0.0
RUN echo $CONT_IMG_VER

docker build --build-arg CONT_IMG_VER=v2.0.1 . outputs v1.0.0

See environment replacement

Built-in args

docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com .

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy
• FTP_PROXY
• ftp_proxy
• NO_PROXY
• no_proxy

Platform-related global args

• docker build --platform=

• Requires BuildKit 18.09+
• DOCKER_BUILDKIT=1

• TARGETPLATFORM - platform of the build result. Eg linux/amd64, linux/arm/v7, windows/amd64.
• TARGETOS - OS component of TARGETPLATFORM
• TARGETARCH - architecture component of TARGETPLATFORM
• TARGETVARIANT - variant component of TARGETPLATFORM
• BUILDPLATFORM - platform of the node performing the build.
• BUILDOS - OS component of BUILDPLATFORM
• BUILDARCH - architecture component of BUILDPLATFORM
• BUILDVARIANT - variant component of BUILDPLATFORM

Cache invalidation by ARG

docker build --build-arg CONT_IMG_VER=v2.0.1 .

1
2
3
4
5
6

RUN echo 123
ARG CONT_IMG_VER
ENV CONT_IMG_VER=$CONT_IMG_VER
RUN echo $CONT_IMG_VER
RUN echo 456
RUN echo 789

• exec count 1: no use cache
• exec count 2: use cache
• exec count 3, but change CONT_IMG_VER=v2.0.2: everything before ARG CONT_IMG_VER used cache; everything after is cache-invalidated

ONBUILD

• ONBUILD <INSTRUCTION>

Notes

• Any build instruction may be registered as a trigger except FROM, MAINTAINER, ONBUILD
• Standardize the base-image build flow; downstream users just follow your trigger setup
• Example: copy source/files into a given dir by default ONBUILD ADD . /app/src or ONBUILD COPY . /app/src
  • Note the Dockerfile must then be at your project root or beside your resource files
  • Exclude files that don’t need to be in the build via .dockerignore

ONBUILD adds a trigger instruction to the image, to run later when this image is used as the base for another build. The trigger runs in the downstream build context as if inserted right after the downstream Dockerfile’s FROM.

This is very useful when you’re building an image meant to be a base for others — e.g. an app build environment or a daemon customizable with user-specific config.

For example, if your image is a reusable Python app builder, you need to add the app source to a specific directory and maybe call a build script afterwards. You can’t just call ADD and RUN now because you don’t have the app source yet, and it differs per app build. You could hand app developers a boilerplate Dockerfile to copy-paste, but that’s inefficient, error-prone, and hard to update, since it’s mixed into app-specific code.

The solution is ONBUILD to register pre-run instructions for the next build stage.

How ONBUILD works

• 1. On encountering ONBUILD, the builder adds a trigger to the image’s metadata. Otherwise it doesn’t affect the current build.
• 2. At the end of the build, all triggers are stored under the OnBuild key in the image manifest. They can be inspected via docker inspect.
• 3. Later, that image can be used as a base via FROM. As part of FROM, the downstream builder looks up the ONBUILD triggers and runs them in registration order. If any trigger fails, FROM aborts, which aborts the build. If all succeed, FROM completes and the build continues.
• 4. Triggers are cleared from the final image after execution — they are not inherited by “child” builds.

STOPSIGNAL

STOPSIGNAL signal

STOPSIGNAL sets the system-call signal sent to the container to exit. It may be a signal name in SIG<name> form (e.g. SIGKILL) or an unsigned number matching a position in the kernel’s syscall table (e.g. 9). If unset, defaults to SIGTERM.

The --stop-signal flag on docker run and docker create overrides the image’s default stop signal per container.

HEALTHCHECK

• HEALTHCHECK [OPTIONS] CMD command (check container health by running a command inside the container)
• HEALTHCHECK NONE (disable any healthcheck inherited from the base image)

Used to detect whether the service in the container is healthy — e.g. stuck in an infinite loop unable to handle new requests while the service still appears “up”.

OPTIONS (all optional):

• --interval=DURATION (default: 30s)
• --timeout=DURATION (default: 30s)
• --start-period=DURATION (default: 0s)
• --retries=N (default: 3)

The command’s exit status indicates health. Values:

• 0: success - the container is healthy and ready for use
• 1: unhealthy - the container is not working correctly
• 2: reserved - do not use this exit code

HEALTHCHECK example

1
2

HEALTHCHECK --interval=5m --timeout=3s \
  CMD curl -f http://localhost/ || exit 1

SHELL

SHELL ["executable", "parameters"]

• SHELL overrides the default shell used for shell-form commands
  • Default shell on Linux is ["/bin/sh", "-c"]
  • Default shell on Windows is ["cmd", "/s", "/c"]
  • SHELL must be written as JSON in the Dockerfile
• SHELL is especially useful on Windows, which has two common, quite different native shells: cmd and powershell, plus optional shells including sh
• SHELL may appear multiple times. Each SHELL overrides all previous ones and affects all later instructions
• If you need another shell — zsh, csh, tcsh, etc. — you can use SHELL on Linux too

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

FROM microsoft/windowsservercore

# Executed as cmd /S /C echo default
RUN echo default

# Executed as cmd /S /C powershell -command Write-Host default
RUN powershell -command Write-Host default

# Executed as powershell -command Write-Host hello
SHELL ["powershell", "-command"]
RUN Write-Host hello

# Executed as cmd /S /C echo hello
SHELL ["cmd", "/S", "/C"]
RUN echo hello

Example

go1.18 base-image build; for more base images see docker-compose-resources

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

FROM v8fg/golang:official-1.18-alpine3.13

LABEL maintainer="278810732@qq.com" github="https://github.com/xwi88" group="https://github.com/v8fg"

# Version of upx to be used(without the 'v' prefix)
# For all releases, see https://github.com/upx/upx/releases
ARG UPX_VERSION=3.96

# Fetch upx, decompress it, make it executable.
ADD https://github.com/upx/upx/releases/download/v${UPX_VERSION}/upx-${UPX_VERSION}-amd64_linux.tar.xz /tmp/upx.tar.xy

RUN apk add --no-cache tzdata git make bash && \
tar -xJOf /tmp/upx.tar.xy upx-${UPX_VERSION}-amd64_linux/upx > /bin/upx \
&& chmod +x /bin/upx && rm /tmp/upx.tar.xy

Best practices

• Each instruction creates a layer. For downstream images the upstream image is a read-only layer; the current build just appends layers on top.
• Prefer COPY over ADD — more transparent and direct
• docker build [OPTIONS] -f PATH; for stdin input use docker build [OPTIONS] -f- PATH
• .dockerignore excludes files that don’t need to be in the build — see dockerignore-file
• Optimize image size
  • Use multi-stage builds to shrink the final image
    • You can target a specific stage: docker build --target builder -t xxxx .
    • A stage can copy from earlier stages or existing images: COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
  • Don’t install unnecessary packages
  • Copy only the files you need (pair with .dockerignore)
  • One container, one concern — avoid running multiple services in one container
  • Compress executables when you can
  • Minimize the layer count
    • Only RUN, COPY, ADD create layers — merge/trim related instructions into one or a few lines
    • Merge and reorder instructions; use a backslash for multi-line; clean up temp files afterwards
    • For pipes, use them directly: RUN set -o pipefail && wget -O - https://some.site | wc -l > /number
• Build-cache invalidation
  • ADD/COPY src changes invalidate later RUN caches
  • ARG/ENV changes invalidate the first instruction that uses them and everything after
• Cache-invalidation tips
  • Push such steps to the end, or replace with other commands
  • Keep src and other references stable
• Only PID=1 can be terminated by docker stop; the sh -c of shell form has PID!=1
• On docker stop, a PID=1 container exits cleanly; after the stop timeout, SIGKILL is sent
• CMD and ENTRYPOINT interaction rules

References

• Docker reference
• understand-how-arg-and-from-interact
• Dockerfile reference
• dockerfile_best-practices
• storage driver
• multistage-build