From 66cfdff64615112cc0ac950d1b31b81608cb0fb2 Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Tue, 28 Mar 2017 10:19:28 -0700 Subject: [PATCH] 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 --- docs/reference/commandline/run.md | 101 +++++++++++------------------- 1 file changed, 36 insertions(+), 65 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index dea7cec763..91f10b5aa2 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -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 `= 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. |