{"id":1340,"date":"2024-10-16T15:19:25","date_gmt":"2024-10-16T15:19:25","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2024\/10\/16\/docker-best-practices-using-arg-and-env-in-your-dockerfiles\/"},"modified":"2024-10-16T15:19:25","modified_gmt":"2024-10-16T15:19:25","slug":"docker-best-practices-using-arg-and-env-in-your-dockerfiles","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2024\/10\/16\/docker-best-practices-using-arg-and-env-in-your-dockerfiles\/","title":{"rendered":"Docker Best Practices: Using ARG and ENV in Your Dockerfiles"},"content":{"rendered":"

If you\u2019ve worked with Docker for any length of time, you\u2019re likely accustomed to writing or at least modifying a Dockerfile<\/a>. This file can be thought of as a recipe for a Docker image; it contains both the ingredients (base images, packages, files) and the instructions (various RUN, COPY, and other commands that help build the image).<\/p>\n

In most cases, Dockerfiles are written once, modified seldom, and used as-is unless something about the project changes. Because these files are created or modified on such an infrequent basis, developers tend to rely on only a handful of frequently used instructions \u2014 RUN, COPY, and EXPOSE being the most common. Other instructions can enhance your image, making it more configurable, manageable, and easier to maintain.\u00a0<\/p>\n

In this post, we will discuss the ARG and ENV instructions and explore why, how, and when to use them.<\/p>\n

ARG: Defining build-time variables<\/h2>\n

The ARG instruction allows you to define variables that will be accessible during the build stage but not available after the image is built. For example, we will use this Dockerfile to build an image where we make the variable specified by the ARG instruction available during the build process.<\/p>\n

\nFROM ubuntu:latest
\nARG THEARG=”foo”
\nRUN echo $THEARG
\nCMD [“env”]\n<\/div>\n

If we run the build, we will see the echo foo line in the output:<\/p>\n

\n$ docker build –no-cache -t argtest .
\n[+] Building 0.4s (6\/6) FINISHED docker:desktop-linux
\n<– SNIP –>
\n => CACHED [1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => [2\/2] RUN echo foo 0.1s
\n => exporting to image 0.0s
\n<– SNIP –>\n<\/div>\n

However, if we run the image and inspect the output of the env command, we do not see THEARG:<\/p>\n

\n$ docker run –rm argtest
\nPATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nHOSTNAME=d19f59677dcd
\nHOME=\/root\n<\/div>\n

ENV: Defining build and runtime variables<\/h2>\n

Unlike ARG, the ENV command allows you to define a variable that can be accessed both at build time and run time:<\/p>\n

\nFROM ubuntu:latest
\nENV THEENV=”bar”
\nRUN echo $THEENV
\nCMD [“env”]\n<\/div>\n

If we run the build, we will see the echo bar line in the output:<\/p>\n

\n$ docker build -t envtest .
\n[+] Building 0.8s (7\/7) FINISHED docker:desktop-linux
\n<– SNIP –>
\n => CACHED [1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => [2\/2] RUN echo bar 0.1s
\n => exporting to image 0.0s
\n<– SNIP –>\n<\/div>\n

If we run the image and inspect the output of the env command, we do see THEENV set, as expected:<\/p>\n

\n$ docker run –rm envtest
\nPATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nHOSTNAME=f53f1d9712a9
\nTHEENV=bar
\nHOME=\/root\n<\/div>\n

Overriding ARG<\/h2>\n

A more advanced use of the ARG instruction is to serve as a placeholder that is then updated at build time:<\/p>\n

\nFROM ubuntu:latest
\nARG THEARG
\nRUN echo $THEARG
\nCMD [“env”]\n<\/div>\n

If we build the image, we see that we are missing a value for $THEARG:<\/p>\n

\n$ docker build -t argtest .
\n<– SNIP –>
\n => CACHED [1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => [2\/2] RUN echo $THEARG 0.1s
\n => exporting to image 0.0s
\n => => exporting layers 0.0s
\n<– SNIP –>\n<\/div>\n

However, we can pass a value for THEARG on the build command line using the –build-arg argument. Notice that we now see THEARG has been replaced with foo in the output:<\/p>\n

\n => CACHED [1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => [2\/2] RUN echo foo 0.1s
\n => exporting to image 0.0s
\n => => exporting layers 0.0s
\n<– SNIP –>\n<\/div>\n

The same can be done in a Docker Compose<\/a> file by using the args key under the build key. Note that these can be set as a mapping (THEARG: foo) or a list (- THEARG=foo):<\/p>\n

\nservices:
\n argtest:
\n build:
\n context: .
\n args:
\n THEARG: foo\n<\/div>\n

If we run docker compose up –build, we can see the THEARG has been replaced with foo in the output:<\/p>\n

\n$ docker compose up –build
\n<– SNIP –>
\n => [argtest 1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => CACHED [argtest 2\/2] RUN echo foo 0.0s
\n => [argtest] exporting to image 0.0s
\n => => exporting layers 0.0s
\n<– SNIP –>
\nAttaching to argtest-1
\nargtest-1 | PATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nargtest-1 | HOSTNAME=d9a3789ac47a
\nargtest-1 | HOME=\/root
\nargtest-1 exited with code 0\n<\/div>\n

Overriding ENV<\/h2>\n

You can also override ENV at build time; this is slightly different from how ARG is overridden. For example, you cannot supply a key without a value with the ENV instruction, as shown in the following example Dockerfile:<\/p>\n

\nFROM ubuntu:latest
\nENV THEENV
\nRUN echo $THEENV
\nCMD [“env”]\n<\/div>\n

When we try to build the image, we receive an error:<\/p>\n

\n$ docker build -t envtest .
\n[+] Building 0.0s (1\/1) FINISHED docker:desktop-linux
\n => [internal] load build definition from Dockerfile 0.0s
\n => => transferring dockerfile: 98B 0.0s
\nDockerfile:3
\n——————–
\n 1 | FROM ubuntu:latest
\n 2 |
\n 3 | >>> ENV THEENV
\n 4 | RUN echo $THEENV
\n 5 |
\n——————–
\nERROR: failed to solve: ENV must have two arguments\n<\/div>\n

However, we can remove the ENV instruction from the Dockerfile:<\/p>\n

\nFROM ubuntu:latest
\nRUN echo $THEENV
\nCMD [“env”]\n<\/div>\n

This allows us to build the image:<\/p>\n

\n$ docker build -t envtest .
\n<– SNIP –>
\n => [1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => CACHED [2\/2] RUN echo $THEENV 0.0s
\n => exporting to image 0.0s
\n => => exporting layers 0.0s
\n<– SNIP –>\n<\/div>\n

Then we can pass an environment variable via the docker run command using the -e flag:<\/p>\n

\n$ docker run –rm -e THEENV=bar envtest
\nPATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nHOSTNAME=638cf682d61f
\nTHEENV=bar
\nHOME=\/root\n<\/div>\n

Although the .env file is usually associated with Docker Compose, it can also be used with docker run.<\/p>\n

\n$ cat .env
\nTHEENV=bar\n

$ docker run –rm –env-file .\/.env envtest
\nPATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nHOSTNAME=59efe1003811
\nTHEENV=bar
\nHOME=\/root\n<\/p><\/div>\n

This can also be done using Docker Compose by using the environment key. Note that we use the variable format for the value:<\/p>\n

\nservices:
\n envtest:
\n build:
\n context: .
\n environment:
\n THEENV: ${THEENV}\n<\/div>\n

If we do not supply a value for THEENV, a warning is thrown:<\/p>\n

\n$ docker compose up –build
\nWARN[0000] The “THEENV” variable is not set. Defaulting to a blank string.
\n<– SNIP –>
\n => [envtest 1\/2] FROM docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04 0.0s
\n => => resolve docker.io\/library\/ubuntu:latest@sha256:8a37d68f4f73ebf3d4efafbcf66379bf3728902a8038616808f04e34a9ab6 0.0s
\n => CACHED [envtest 2\/2] RUN echo ${THEENV} 0.0s
\n => [envtest] exporting to image 0.0s
\n<– SNIP –>
\n \u2714 Container dd-envtest-1 Recreated 0.1s
\nAttaching to envtest-1
\nenvtest-1 | PATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nenvtest-1 | HOSTNAME=816d164dc067
\nenvtest-1 | THEENV=
\nenvtest-1 | HOME=\/root
\nenvtest-1 exited with code 0\n<\/div>\n

The value for our variable can be supplied in several different ways, as follows:<\/p>\n

On the compose command line:<\/strong><\/p>\n

\n$ THEENV=bar docker compose up\n

[+] Running 2\/0
\n \u2714 Synchronized File Shares 0.0s
\n \u2714 Container dd-envtest-1 Recreated 0.1s
\nAttaching to envtest-1
\nenvtest-1 | PATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nenvtest-1 | HOSTNAME=20f67bb40c6a
\nenvtest-1 | THEENV=bar
\nenvtest-1 | HOME=\/root
\nenvtest-1 exited with code 0\n<\/p><\/div>\n

In the shell environment on the host system:<\/strong><\/p>\n

\n$ export THEENV=bar
\n$ docker compose up\n

[+] Running 2\/0
\n \u2714 Synchronized File Shares 0.0s
\n \u2714 Container dd-envtest-1 Created 0.0s
\nAttaching to envtest-1
\nenvtest-1 | PATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nenvtest-1 | HOSTNAME=20f67bb40c6a
\nenvtest-1 | THEENV=bar
\nenvtest-1 | HOME=\/root
\nenvtest-1 exited with code 0\n<\/p><\/div>\n

In the special .env file:<\/strong><\/p>\n

\n$ cat .env
\nTHEENV=bar\n

$ docker compose up<\/p>\n

[+] Running 2\/0
\n \u2714 Synchronized File Shares 0.0s
\n \u2714 Container dd-envtest-1 Created 0.0s
\nAttaching to envtest-1
\nenvtest-1 | PATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nenvtest-1 | HOSTNAME=20f67bb40c6a
\nenvtest-1 | THEENV=bar
\nenvtest-1 | HOME=\/root
\nenvtest-1 exited with code 0\n<\/p><\/div>\n

Finally, when running services directly using docker compose run, you can use the -e flag to override the .env file.<\/p>\n

\n$ docker compose run -e THEENV=bar envtest\n

[+] Creating 1\/0
\n \u2714 Synchronized File Shares 0.0s
\nPATH=\/usr\/local\/sbin:\/usr\/local\/bin:\/usr\/sbin:\/usr\/bin:\/sbin:\/bin
\nHOSTNAME=219e96494ddd
\nTERM=xterm
\nTHEENV=bar
\nHOME=\/root\n<\/p><\/div>\n

The tl;dr<\/h2>\n

If you need to access a variable during the build process but not at runtime, use ARG. If you need to access the variable both during the build and at runtime, or only at runtime, use ENV.<\/p>\n

To decide between them, consider the following flow (Figure 1):<\/p>\n