Cheat Sheet for Using Environment Variables in Docker (and docker-compose)

gist-cheatsheet-env-vars-in-docker.md

Docker Environment Variables Cheat Sheet

There are two sets of separate and independent environment variables to consider in Docker...

1. Local environment variables in the shell where you are calling the docker/docker-compose commands, like your laptop, CI/CD, or production server)
2. Container environment variables in your running containers

There are two basic concepts when using environment variables in Docker...

1. Environment variable substitution in your docker-compose files
2. Setting the container environment variables in docker and docker-compose

---

Environment Variable Substitution in docker-compose

Documentation: https://docs.docker.com/compose/compose-file/compose-file-v3/#variable-substitution

• Both $VARIABLE and ${VARIABLE} syntax can be used

• Environment variable (.env) files can be used both to set values for any defined environment variables in your containers and to configure docker-compose settings

• To match the exact state of the local environment variable (i.e. not set, set but empty, set with value), use the raw environment variable on the "left hand side", for example in .env...

  TAG
  

  Or for example in setting container environment variables in docker-compose.yml...

  version: '3.4'
  services:
    targetapp:
      image: target-app:${TAG}
      environment:
        - DB_NAME

• Docker supports the typical *nix shell default values syntax:

  This Variable Substitution...	Sets the default value default IF...
  ${ENVIRONMENTVARIABLE-default}	ENVIRONMENTVARIABLE is Not Set
  ${ENVIRONMENTVARIABLE:-default}	ENVIRONMENTVARIABLE is Not Set or Empty

• Docker supports the typical *nix shell variable error syntax:

  This Variable Substitution...	Exits with an Error Message err IF...
  ${ENVIRONMENTVARIABLE?err}	ENVIRONMENTVARIABLE is Not Set
  ${ENVIRONMENTVARIABLE:?err}	ENVIRONMENTVARIABLE is Not Set or Empty

---

Using Environment Variable Files in docker-compose

Documentation: https://docs.docker.com/compose/environment-variables/#the-env-file

• By default, docker-compose will look for a file named .env in the directory where you are running the docker-compose command

Documentation: https://docs.docker.com/compose/environment-variables/#using-the---env-file--option

• Specify a different environment variable file using the --env-file option with the docker-compose commands, for example...

  % docker-compose --env-file .env.staging config
  

• Specify an environment file in docker-compose.yml file using the env_file key under the service, for example...

  version: '3.4'
  services:
    targetapp:
      image: target-app:${TAG}
      environment:
        - DB_NAME
      env_file: .env.staging

• Local environment variables take precedence over those in .env or specified by --env-file

---

Setting Container Environment Variables in docker run

Documentation: https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file

• Use the docker run -e (or docker run --env) option to set an environment variable in the container, for example...

  % docker run -e MY_USERNAME=tomsmith --env MY_PASSWORD=SuperSecretPassword! target-app
  

• Use local environment variable substitution, for example...

  % DB_NAME=Sales docker run --env DB_NAME target-app
  

• Use the docker run --env-file option to specify a file to set the container's environment variables, for example...

  % docker run --env-file .env target-app
  

---

Setting Container Environment Variables in docker-compose

Documentation: https://docs.docker.com/compose/environment-variables/

• Use the docker-compose run -e option to set container environment variables on the command line in docker-compose, for example...

  % docker-compose run -e MY_USERNAME=tomsmith -e MY_PASSWORD=SuperSecretPassword! targetapp
  

• Use local environment variable substitution, for example...

  % DB_NAME=Sales docker-compose run -e DB_NAME target-app
  

• Use the environment key under your service in the docker-compose.yml file to set your container environment variables, for example...

  version: '3.4'
  services:
    targetapp:
      image: target-app:${TAG}
      environment:
        - MY_USERNAME=tomsmith
        - MY_PASSWORD

• Use the env_file key under your service in the docker-compose.yml file to specify an environment file to set your container environment variables, for example...

  version: '3.4'
  services:
    targetapp:
      image: target-app:${TAG}
      environment:
        - DB_NAME
      env_file: .env.staging

• Here is the order of precedence for setting container environment variables in docker-compose...

  1. Environment variable settings in the docker-compose file
  2. Local environment variables
  3. Environment file
  4. Dockerfile

---