Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clean `docker run -e` reference docs 

Simplified the docs on how to set environment variables in a
container. Makes it clear that you have three options, and how
to use them.

Signed-off-by: Joao Fernandes <joao.fernandes@docker.com>
This commit is contained in:
Joao Fernandes 2017-03-28 10:19:28 -07:00 committed by Tibor Vass
parent 71b0f91129
commit 66cfdff646
1 changed files with 36 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/reference/commandline/run.md
View File

@ -365,75 +365,46 @@ system's interfaces.
$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
```
This sets simple (non-array) environmental variables in the container. For
illustration all three
flags are shown here. Where `-e`, `--env` take an environment variable and
value, or if no `=` is provided, then that variable's current value, set via
`export`, is passed through (i.e. `$MYVAR1` from the host is set to `$MYVAR1`
in the container). When no `=` is provided and that variable is not defined
in the client's environment then that variable will be removed from the
container's list of environment variables. All three flags, `-e`, `--env` and
`--env-file` can be repeated.
Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array)
environment variables in the container you're running, or overwrite variables
that are defined in the Dockerfile of the image you're running.
Regardless of the order of these three flags, the `--env-file` are processed
first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will
override variables as needed.
You can define the variable and its value when running the container:
```bash
$ cat ./env.list
TEST_FOO=BAR
$ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
TEST_FOO=This is a test
$ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR
VAR1=value1
VAR2=value2
```
The `--env-file` flag takes a filename as an argument and expects each line
to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment
lines need only be prefixed with `#`
An example of a file passed with `--env-file`
You can also use variables that you've exported to your local environment:
```bash
$ cat ./env.list
TEST_FOO=BAR
export VAR1=value1
export VAR2=value2
# this is a comment
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
123qwe=bar
org.spring.config=something
$ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR
VAR1=value1
VAR2=value2
```
# pass through this variable from the caller
TEST_PASSTHROUGH
$ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=5198e0745561
TEST_FOO=BAR
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
TEST_PASSTHROUGH=howdy
HOME=/root
123qwe=bar
org.spring.config=something
When running the command, the Docker CLI client checks the value the variable
has in your local environment and passes it to the container.
If no `=` is provided and that variable is not exported in your local
environment, the variable won't be set in the container.
$ docker run --env-file ./env.list busybox env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=5198e0745561
TEST_FOO=BAR
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
TEST_PASSTHROUGH=
HOME=/root
123qwe=bar
org.spring.config=something
You can also load the environment variables from a file. This file should use
the syntax `<variable>= value`, and `#` for comments.
```bash
$ cat env.list
# This is a comment
VAR1=value1
VAR2=value2
$ docker run --env-file env.list ubuntu env | grep VAR
VAR1=value1
VAR2=value2
```
### Set metadata on container (-l, --label, --label-file)
@ -615,11 +586,11 @@ Use Docker's `--restart` to specify a container's *restart policy*. A restart
policy controls whether the Docker daemon restarts a container after exit.
Docker supports the following restart policies:
| Policy | Result |
|-------------------|-----------------------------------------|
| `no` | Do not automatically restart the container when it exits. This is the default. |
| `failure` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. |
| `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
| Policy | Result |
|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `no` | Do not automatically restart the container when it exits. This is the default. |
| `failure` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. |
| `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
```bash
$ docker run --restart=always redis
@ -744,7 +715,7 @@ On Windows, `--isolation` can take one of these values:
| Value | Description |
|-----------|--------------------------------------------------------------------------------------------|
|:----------|:-------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). |
| `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems). |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |