From 259aa9005916ccb2395e448ad2f309ca4dff527c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 21:42:03 +0100 Subject: [PATCH] docs: rewrite section on filesystem mounts Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 122 ++++++++++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 46 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 3b6afa2848..3db59d7997 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -189,6 +189,82 @@ round-trip min/avg/max = 0.257/0.288/0.326 ms For more information about container networking, see [Networking overview](https://docs.docker.com/network/) +## Filesystem mounts + +By default, the data in a container is stored in an ephemeral, writable +container layer. Removing the container also removes its data. If you want to +use persistent data with containers, you can use filesystem mounts to store the +data persistently on the host system. Filesystem mounts can also let you share +data between containers and the host. + +Docker supports two main categories of mounts: + +- Volume mounts +- Bind mounts + +Volume mounts are great for persistently storing data for containers, and for +sharing data between containers. Bind mounts, on the other hand, are for +sharing data between a container and the host. + +You can add a filesystem mount to a container using the `--mount` flag for the +`docker run` command. + +The following sections show basic examples of how to create volumes and bind +mounts. For more in-depth examples and descriptions, refer to the section of +the [storage section](https://docs.docker.com/storage/) in the documentation. + +### Volume mounts + +To create a volume mount: + +```console +$ docker run --mount source=,target=[PATH] [IMAGE] [COMMAND...] +``` + +The `--mount` flag takes two parameters in this case: `source` and `target`. +The value for the `source` parameter is the name of the volume. The value of +`target` is the mount location of the volume inside the container. Once you've +created the volume, any data you write to the volume is persisted, even if you +stop or remove the container: + +```console +$ docker run --rm --mount source=my_volume,target=/foo busybox \ + echo "hello, volume!" > /foo/hello.txt +$ docker run --mount source=my_volume,target=/bar busybox + cat /bar/hello.txt +hello, volume! +``` + +The `target` must always be an absolute path, such as `/src/docs`. An absolute +path starts with a `/` (forward slash). Volume names must start with an +alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or +`-` (hyphen). + +### Bind mounts + +To create a bind mount: + +```console +$ docker run -it --mount type=bind,source=[PATH],target=[PATH] busybox +``` + +In this case, the `--mount` flag takes three parameters. A type (`bind`), and +two paths. The `source` path is a the location on the host that you want to +bind mount into the container. The `target` path is the mount destination +inside the container. + +Bind mounts are read-write by default, meaning that you can both read and write +files to and from the mounted location from the container. Changes that you +make, such as adding or editing files, are reflected on the host filesystem: + +```console +$ docker run -it --mount type=bind,source=.,target=/foo busybox +/ # echo "hello from container" > /foo/hello.txt +/ # exit +$ cat hello.txt +hello from container +``` + ## Exit status The exit code from `docker run` gives information about why the container @@ -900,7 +976,6 @@ override those defaults using flags for the `docker run` command. - [Expose ports](#exposed-ports) - [Environment variables](#environment-variables) - [Healthcheck](#healthchecks) -- [Filesystem mounts](#filesystem-mounts) - [User](#user) - [Working directory](#working-directory) @@ -1130,51 +1205,6 @@ $ sleep 2; docker inspect --format='{{json .State.Health}}' test The health status is also displayed in the `docker ps` output. -### Filesystem mounts - - -v, --volume=[host-src:]container-dest[:]: Bind mount a volume. - The comma-delimited `options` are [rw|ro], [z|Z], - [[r]shared|[r]slave|[r]private], and [nocopy]. - The 'host-src' is an absolute path or a name value. - - If neither 'rw' or 'ro' is specified then the volume is mounted in - read-write mode. - - The `nocopy` mode is used to disable automatically copying the requested volume - path in the container to the volume storage location. - For named volumes, `copy` is the default mode. Copy modes are not supported - for bind-mounted volumes. - - --volumes-from="": Mount all volumes from the given container(s) - -> **Note** -> -> When using systemd to manage the Docker daemon's start and stop, in the systemd -> unit file there is an option to control mount propagation for the Docker daemon -> itself, called `MountFlags`. The value of this setting may cause Docker to not -> see mount propagation changes made on the mount point. For example, if this value -> is `slave`, you may not be able to use the `shared` or `rshared` propagation on -> a volume. - -The volumes commands are complex enough to have their own documentation -in section [*Use volumes*](https://docs.docker.com/storage/volumes/). A developer can define -one or more `VOLUME`'s associated with an image, but only the operator -can give access from one container to another (or from a container to a -volume mounted on the host). - -The `container-dest` must always be an absolute path such as `/src/docs`. -The `host-src` can either be an absolute path or a `name` value. If you -supply an absolute path for the `host-src`, Docker bind-mounts to the path -you specify. If you supply a `name`, Docker creates a named volume by that `name`. - -A `name` value must start with an alphanumeric character, -followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). -An absolute path starts with a `/` (forward slash). - -For example, you can specify either `/foo` or `foo` for a `host-src` value. -If you supply the `/foo` value, Docker creates a bind mount. If you supply -the `foo` specification, Docker creates a named volume. - ### User `root` (id = 0) is the default user within a container. The image developer can