Docker Environment Variables Cheat Sheet

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

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

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

Environment Variable Substitution in docker-compose

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

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

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

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
```

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