Merge pull request #16617 from zhangjianfnst/15869-improve-commandline-doc
Improve the way we deliver Examples in command line.
This commit is contained in:
Sebastiaan van Stijn
commit
2b4128e904
2 changed files with 98 additions and 57 deletions
|
|
@ -128,6 +128,8 @@ See also:
|
|||
|
||||
## Examples
|
||||
|
||||
### Build with PATH
|
||||
|
||||
$ docker build .
|
||||
Uploading context 10240 bytes
|
||||
Step 1 : FROM busybox
|
||||
|
|
@ -168,6 +170,31 @@ The transfer of context from the local machine to the Docker daemon is what the
|
|||
If you wish to keep the intermediate containers after the build is complete,
|
||||
you must use `--rm=false`. This does not affect the build cache.
|
||||
|
||||
### Build with URL
|
||||
|
||||
$ docker build github.com/creack/docker-firefox
|
||||
|
||||
This will clone the GitHub repository and use the cloned repository as context.
|
||||
The Dockerfile at the root of the repository is used as Dockerfile. Note that
|
||||
you can specify an arbitrary Git repository by using the `git://` or `git@`
|
||||
schema.
|
||||
|
||||
### Build with -
|
||||
|
||||
$ docker build - < Dockerfile
|
||||
|
||||
This will read a Dockerfile from `STDIN` without context. Due to the lack of a
|
||||
context, no contents of any local directory will be sent to the Docker daemon.
|
||||
Since there is no context, a Dockerfile `ADD` only works if it refers to a
|
||||
remote URL.
|
||||
|
||||
$ docker build - < context.tar.gz
|
||||
|
||||
This will build an image for a compressed context read from `STDIN`. Supported
|
||||
formats are: bzip2, gzip and xz.
|
||||
|
||||
### Usage of .dockerignore
|
||||
|
||||
$ docker build .
|
||||
Uploading context 18.829 MB
|
||||
Uploading context
|
||||
|
|
@ -193,29 +220,14 @@ directory from the context. Its effect can be seen in the changed size of the
|
|||
uploaded context. The builder reference contains detailed information on
|
||||
[creating a .dockerignore file](../builder.md#dockerignore-file)
|
||||
|
||||
### Tag image (-t)
|
||||
|
||||
$ docker build -t vieux/apache:2.0 .
|
||||
|
||||
This will build like the previous example, but it will then tag the resulting
|
||||
image. The repository name will be `vieux/apache` and the tag will be `2.0`
|
||||
|
||||
$ docker build - < Dockerfile
|
||||
|
||||
This will read a Dockerfile from `STDIN` without context. Due to the lack of a
|
||||
context, no contents of any local directory will be sent to the Docker daemon.
|
||||
Since there is no context, a Dockerfile `ADD` only works if it refers to a
|
||||
remote URL.
|
||||
|
||||
$ docker build - < context.tar.gz
|
||||
|
||||
This will build an image for a compressed context read from `STDIN`. Supported
|
||||
formats are: bzip2, gzip and xz.
|
||||
|
||||
$ docker build github.com/creack/docker-firefox
|
||||
|
||||
This will clone the GitHub repository and use the cloned repository as context.
|
||||
The Dockerfile at the root of the repository is used as Dockerfile. Note that
|
||||
you can specify an arbitrary Git repository by using the `git://` or `git@`
|
||||
schema.
|
||||
### Specify Dockerfile (-f)
|
||||
|
||||
$ docker build -f Dockerfile.debug .
|
||||
|
||||
|
|
@ -248,14 +260,20 @@ the command line.
|
|||
> repeatable builds on remote Docker hosts. This is also the reason why
|
||||
> `ADD ../file` will not work.
|
||||
|
||||
### Optional parent cgroup (--cgroup-parent)
|
||||
|
||||
When `docker build` is run with the `--cgroup-parent` option the containers
|
||||
used in the build will be run with the [corresponding `docker run`
|
||||
flag](../run.md#specifying-custom-cgroups).
|
||||
|
||||
### Set ulimits in container (--ulimit)
|
||||
|
||||
Using the `--ulimit` option with `docker build` will cause each build step's
|
||||
container to be started using those [`--ulimit`
|
||||
flag values](../run.md#setting-ulimits-in-a-container).
|
||||
|
||||
### Set build-time variables (--build-arg)
|
||||
|
||||
You can use `ENV` instructions in a Dockerfile to define variable
|
||||
values. These values persist in the built image. However, often
|
||||
persistence is not what you want. Users want to specify variables differently
|
||||
|
|
@ -263,7 +281,7 @@ depending on which host they build an image on.
|
|||
|
||||
A good example is `http_proxy` or source versions for pulling intermediate
|
||||
files. The `ARG` instruction lets Dockerfile authors define values that users
|
||||
can set at build-time using the `---build-arg` flag:
|
||||
can set at build-time using the `--build-arg` flag:
|
||||
|
||||
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .
|
||||
|
||||
|
|
|
|||
|
|
@ -92,6 +92,8 @@ and linking containers.
|
|||
|
||||
## Examples
|
||||
|
||||
### Assign name and allocate psuedo-TTY (--name, -it)
|
||||
|
||||
$ docker run --name test -it debian
|
||||
root@d6c0fe130dba:/# exit 13
|
||||
$ echo $?
|
||||
|
|
@ -106,6 +108,8 @@ In the example, the `bash` shell is quit by entering
|
|||
`exit 13`. This exit code is passed on to the caller of
|
||||
`docker run`, and is recorded in the `test` container's metadata.
|
||||
|
||||
### Capture container ID (--cidfile)
|
||||
|
||||
$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
|
||||
|
||||
This will create a container and print `test` to the console. The `cidfile`
|
||||
|
|
@ -113,6 +117,8 @@ flag makes Docker attempt to create a new file and write the container ID to it.
|
|||
If the file exists already, Docker will return an error. Docker will close this
|
||||
file when `docker run` exits.
|
||||
|
||||
### Full container capabilities (--privileged)
|
||||
|
||||
$ docker run -t -i --rm ubuntu bash
|
||||
root@bc338942ef20:/# mount -t tmpfs none /mnt
|
||||
mount: permission denied
|
||||
|
|
@ -132,11 +138,15 @@ lifts all the limitations enforced by the `device` cgroup controller. In other
|
|||
words, the container can then do almost everything that the host can do. This
|
||||
flag exists to allow special use-cases, like running Docker within Docker.
|
||||
|
||||
### Set working directory (-w)
|
||||
|
||||
$ docker run -w /path/to/dir/ -i -t ubuntu pwd
|
||||
|
||||
The `-w` lets the command being executed inside directory given, here
|
||||
`/path/to/dir/`. If the path does not exists it is created inside the container.
|
||||
|
||||
### Mount volume (-v, --read-only)
|
||||
|
||||
$ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd
|
||||
|
||||
The `-v` flag mounts the current working directory into the container. The `-w`
|
||||
|
|
@ -166,6 +176,8 @@ binary (such as that provided by [https://get.docker.com](
|
|||
https://get.docker.com)), you give the container the full access to create and
|
||||
manipulate the host's Docker daemon.
|
||||
|
||||
### Publish or expose port (-p, --expose)
|
||||
|
||||
$ docker run -p 127.0.0.1:80:8080 ubuntu bash
|
||||
|
||||
This binds port `8080` of the container to port `80` on `127.0.0.1` of
|
||||
|
|
@ -179,6 +191,8 @@ publishing the port to the host system's interfaces. The [Docker User
|
|||
Guide](../../userguide/dockerlinks.md) explains in detail how to manipulate
|
||||
ports in Docker.
|
||||
|
||||
### Set environment variables (-e, --env, --env-file)
|
||||
|
||||
$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
|
||||
|
||||
This sets environmental variables in the container. For illustration all three
|
||||
|
|
@ -247,7 +261,9 @@ An example of a file passed with `--env-file`
|
|||
123qwe=bar
|
||||
org.spring.config=something
|
||||
|
||||
A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:
|
||||
### Set metadata on container (-l, --label, --label-file)
|
||||
|
||||
A label is a `key=value` pair that applies metadata to a container. To label a container with two labels:
|
||||
|
||||
$ docker run -l my-label --label com.example.foo=bar ubuntu bash
|
||||
|
||||
|
|
@ -281,6 +297,8 @@ For additional information on working with labels, see [*Labels - custom
|
|||
metadata in Docker*](../../userguide/labels-custom-metadata.md) in the Docker User
|
||||
Guide.
|
||||
|
||||
### Add link to another container (--link)
|
||||
|
||||
$ docker run --link /redis:redis --name console ubuntu bash
|
||||
|
||||
The `--link` flag will link the container named `/redis` into the newly
|
||||
|
|
@ -295,6 +313,8 @@ example as:
|
|||
The `--name` flag will assign the name `console` to the newly created
|
||||
container.
|
||||
|
||||
### Mount volumes from container (--volumes-from)
|
||||
|
||||
$ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
|
||||
|
||||
The `--volumes-from` flag mounts all the defined volumes from the referenced
|
||||
|
|
@ -317,6 +337,8 @@ content label. Shared volume labels allow all containers to read/write content.
|
|||
The `Z` option tells Docker to label the content with a private unshared label.
|
||||
Only the current container can use a private volume.
|
||||
|
||||
### Attach to STDIN/STDOUT/STDERR (-a)
|
||||
|
||||
The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT`
|
||||
or `STDERR`. This makes it possible to manipulate the output and input as
|
||||
needed.
|
||||
|
|
@ -340,6 +362,8 @@ logs could be retrieved using `docker logs`. This is
|
|||
useful if you need to pipe a file or something else into a container and
|
||||
retrieve the container's ID once the container has finished running.
|
||||
|
||||
### Add host device to container (--device)
|
||||
|
||||
$ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
|
||||
brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc
|
||||
brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd
|
||||
|
|
@ -375,38 +399,7 @@ flag:
|
|||
> that may be removed should not be added to untrusted containers with
|
||||
> `--device`.
|
||||
|
||||
**A complete example:**
|
||||
|
||||
$ docker run -d --name static static-web-files sh
|
||||
$ docker run -d --expose=8098 --name riak riakserver
|
||||
$ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
|
||||
$ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
|
||||
$ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
|
||||
|
||||
This example shows five containers that might be set up to test a web
|
||||
application change:
|
||||
|
||||
1. Start a pre-prepared volume image `static-web-files` (in the background)
|
||||
that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
|
||||
the Dockerfile to allow the web server to use those files);
|
||||
2. Start a pre-prepared `riakserver` image, give the container name `riak` and
|
||||
expose port `8098` to any containers that link to it;
|
||||
3. Start the `appserver` image, restricting its memory usage to 100MB, setting
|
||||
two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
|
||||
current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
|
||||
4. Start the `webserver`, mapping port `443` in the container to port `1443` on
|
||||
the Docker server, setting the DNS server to `10.0.0.1` and DNS search
|
||||
domain to `dev.org`, creating a volume to put the log files into (so we can
|
||||
access it from another container), then importing the files from the volume
|
||||
exposed by the `static` container, and linking to all exposed ports from
|
||||
`riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
|
||||
consistent with the pre-generated SSL certificate;
|
||||
5. Finally, we create a container that runs `tail -f access.log` using the logs
|
||||
volume from the `web` container, setting the workdir to `/var/log/httpd`. The
|
||||
`--rm` option means that when the container exits, the container's layer is
|
||||
removed.
|
||||
|
||||
## Restart policies
|
||||
### Restart policies (--restart)
|
||||
|
||||
Use Docker's `--restart` to specify a container's *restart policy*. A restart
|
||||
policy controls whether the Docker daemon restarts a container after exit.
|
||||
|
|
@ -468,7 +461,7 @@ More detailed information on restart policies can be found in the
|
|||
[Restart Policies (--restart)](../run.md#restart-policies-restart)
|
||||
section of the Docker run reference page.
|
||||
|
||||
## Adding entries to a container hosts file
|
||||
### Add entries to container hosts file (--add-host)
|
||||
|
||||
You can add other hosts into a container's `/etc/hosts` file by using one or
|
||||
more `--add-host` flags. This example adds a static address for a host named
|
||||
|
|
@ -499,7 +492,7 @@ For IPv6 use the `-6` flag instead of the `-4` flag. For other network
|
|||
devices, replace `eth0` with the correct device name (for example `docker0`
|
||||
for the bridge device).
|
||||
|
||||
### Setting ulimits in a container
|
||||
### Set ulimits in container (--ulimit)
|
||||
|
||||
Since setting `ulimit` settings in a container requires extra privileges not
|
||||
available in the default container, you can set these using the `--ulimit` flag.
|
||||
|
|
@ -519,13 +512,12 @@ available in the default container, you can set these using the `--ulimit` flag.
|
|||
The values are sent to the appropriate `syscall` as they are set.
|
||||
Docker doesn't perform any byte conversion. Take this into account when setting the values.
|
||||
|
||||
#### For `nproc` usage:
|
||||
#### For `nproc` usage
|
||||
|
||||
Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the
|
||||
maximum number of processes available to a user, not to a container. For example, start four
|
||||
containers with `daemon` user:
|
||||
|
||||
|
||||
docker run -d -u daemon --ulimit nproc=3 busybox top
|
||||
docker run -d -u daemon --ulimit nproc=3 busybox top
|
||||
docker run -d -u daemon --ulimit nproc=3 busybox top
|
||||
|
|
@ -535,8 +527,39 @@ The 4th container fails and reports "[8] System error: resource temporarily unav
|
|||
This fails because the caller set `nproc=3` resulting in the first three containers using up
|
||||
the three processes quota set for the `daemon` user.
|
||||
|
||||
### Stopping a container with a specific signal
|
||||
### Stop container with signal (--stop-signal)
|
||||
|
||||
The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
|
||||
This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
|
||||
or a signal name in the format SIGNAME, for instance SIGKILL.
|
||||
|
||||
### A complete example
|
||||
|
||||
$ docker run -d --name static static-web-files sh
|
||||
$ docker run -d --expose=8098 --name riak riakserver
|
||||
$ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
|
||||
$ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
|
||||
$ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
|
||||
|
||||
This example shows five containers that might be set up to test a web
|
||||
application change:
|
||||
|
||||
1. Start a pre-prepared volume image `static-web-files` (in the background)
|
||||
that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
|
||||
the Dockerfile to allow the web server to use those files);
|
||||
2. Start a pre-prepared `riakserver` image, give the container name `riak` and
|
||||
expose port `8098` to any containers that link to it;
|
||||
3. Start the `appserver` image, restricting its memory usage to 100MB, setting
|
||||
two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
|
||||
current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
|
||||
4. Start the `webserver`, mapping port `443` in the container to port `1443` on
|
||||
the Docker server, setting the DNS server to `10.0.0.1` and DNS search
|
||||
domain to `dev.org`, creating a volume to put the log files into (so we can
|
||||
access it from another container), then importing the files from the volume
|
||||
exposed by the `static` container, and linking to all exposed ports from
|
||||
`riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
|
||||
consistent with the pre-generated SSL certificate;
|
||||
5. Finally, we create a container that runs `tail -f access.log` using the logs
|
||||
volume from the `web` container, setting the workdir to `/var/log/httpd`. The
|
||||
`--rm` option means that when the container exits, the container's layer is
|
||||
removed.
|
||||
Loading…
Reference in a new issue