github.com/portworx/docker@v1.12.1/docs/tutorials/dockervolumes.md (about) 1 <!--[metadata]> 2 +++ 3 aliases = [ 4 "/engine/userguide/containers/dockervolumes/", 5 "/engine/userguide/dockervolumes/" 6 ] 7 title = "Manage data in containers" 8 description = "How to manage data inside your Docker containers." 9 keywords = ["Examples, Usage, volume, docker, documentation, user guide, data, volumes"] 10 [menu.main] 11 parent = "engine_learn_menu" 12 +++ 13 <![end-metadata]--> 14 15 # Manage data in containers 16 17 So far you've been introduced to some [basic Docker 18 concepts](usingdocker.md), seen how to work with [Docker 19 images](dockerimages.md) as well as learned about [networking and 20 links between containers](../userguide/networking/default_network/dockerlinks.md). In this 21 section you're going to learn how you can manage data inside and between your 22 Docker containers. 23 24 You're going to look at the two primary ways you can manage data with 25 Docker Engine. 26 27 * Data volumes 28 * Data volume containers 29 30 ## Data volumes 31 32 A *data volume* is a specially-designated directory within one or more 33 containers that bypasses the [*Union File System*](../reference/glossary.md#union-file-system). Data volumes provide several useful features for persistent or shared data: 34 35 - Volumes are initialized when a container is created. If the container's 36 base image contains data at the specified mount point, that existing data is 37 copied into the new volume upon volume initialization. (Note that this does 38 not apply when [mounting a host directory](#mount-a-host-directory-as-a-data-volume).) 39 - Data volumes can be shared and reused among containers. 40 - Changes to a data volume are made directly. 41 - Changes to a data volume will not be included when you update an image. 42 - Data volumes persist even if the container itself is deleted. 43 44 Data volumes are designed to persist data, independent of the container's life 45 cycle. Docker therefore *never* automatically deletes volumes when you remove 46 a container, nor will it "garbage collect" volumes that are no longer 47 referenced by a container. 48 49 ### Adding a data volume 50 51 You can add a data volume to a container using the `-v` flag with the 52 `docker create` and `docker run` command. You can use the `-v` multiple times 53 to mount multiple data volumes. Now, mount a single volume in your web 54 application container. 55 56 ```bash 57 $ docker run -d -P --name web -v /webapp training/webapp python app.py 58 ``` 59 60 This will create a new volume inside a container at `/webapp`. 61 62 > **Note:** 63 > You can also use the `VOLUME` instruction in a `Dockerfile` to add one or 64 > more new volumes to any container created from that image. 65 66 ### Locating a volume 67 68 You can locate the volume on the host by utilizing the `docker inspect` command. 69 70 ```bash 71 $ docker inspect web 72 ``` 73 74 The output will provide details on the container configurations including the 75 volumes. The output should look something similar to the following: 76 77 ```json 78 ... 79 "Mounts": [ 80 { 81 "Name": "fac362...80535", 82 "Source": "/var/lib/docker/volumes/fac362...80535/_data", 83 "Destination": "/webapp", 84 "Driver": "local", 85 "Mode": "", 86 "RW": true, 87 "Propagation": "" 88 } 89 ] 90 ... 91 ``` 92 93 You will notice in the above `Source` is specifying the location on the host and 94 `Destination` is specifying the volume location inside the container. `RW` shows 95 if the volume is read/write. 96 97 ### Mount a host directory as a data volume 98 99 In addition to creating a volume using the `-v` flag you can also mount a 100 directory from your Docker engine's host into a container. 101 102 ```bash 103 $ docker run -d -P --name web -v /src/webapp:/opt/webapp training/webapp python app.py 104 ``` 105 106 This command mounts the host directory, `/src/webapp`, into the container at 107 `/opt/webapp`. If the path `/opt/webapp` already exists inside the container's 108 image, the `/src/webapp` mount overlays but does not remove the pre-existing 109 content. Once the mount is removed, the content is accessible again. This is 110 consistent with the expected behavior of the `mount` command. 111 112 The `container-dir` must always be an absolute path such as `/src/docs`. 113 The `host-dir` can either be an absolute path or a `name` value. If you 114 supply an absolute path for the `host-dir`, Docker bind-mounts to the path 115 you specify. If you supply a `name`, Docker creates a named volume by that `name`. 116 117 A `name` value must start with an alphanumeric character, 118 followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). 119 An absolute path starts with a `/` (forward slash). 120 121 For example, you can specify either `/foo` or `foo` for a `host-dir` value. 122 If you supply the `/foo` value, the Docker Engine creates a bind-mount. If you supply 123 the `foo` specification, the Docker Engine creates a named volume. 124 125 If you are using Docker Machine on Mac or Windows, your Docker Engine daemon has only 126 limited access to your OS X or Windows filesystem. Docker Machine tries to 127 auto-share your `/Users` (OS X) or `C:\Users` (Windows) directory. So, you can 128 mount files or directories on OS X using. 129 130 ```bash 131 docker run -v /Users/<path>:/<container path> ... 132 ``` 133 134 On Windows, mount directories using: 135 136 ```bash 137 docker run -v /c/Users/<path>:/<container path> ...` 138 ``` 139 140 All other paths come from your virtual machine's filesystem, so if you want 141 to make some other host folder available for sharing, you need to do 142 additional work. In the case of VirtualBox you need to make the host folder 143 available as a shared folder in VirtualBox. Then, you can mount it using the 144 Docker `-v` flag. 145 146 Mounting a host directory can be useful for testing. For example, you can mount 147 source code inside a container. Then, change the source code and see its effect 148 on the application in real time. The directory on the host must be specified as 149 an absolute path and if the directory doesn't exist the Docker Engine daemon 150 automatically creates it for you. 151 152 Docker volumes default to mount in read-write mode, but you can also set it to 153 be mounted read-only. 154 155 ```bash 156 $ docker run -d -P --name web -v /src/webapp:/opt/webapp:ro training/webapp python app.py 157 ``` 158 159 Here you've mounted the same `/src/webapp` directory but you've added the `ro` 160 option to specify that the mount should be read-only. 161 162 Because of [limitations in the `mount` 163 function](http://lists.linuxfoundation.org/pipermail/containers/2015-April/035788.html), 164 moving subdirectories within the host's source directory can give 165 access from the container to the host's file system. This requires a malicious 166 user with access to host and its mounted directory. 167 168 >**Note**: The host directory is, by its nature, host-dependent. For this 169 >reason, you can't mount a host directory from `Dockerfile` because built images 170 >should be portable. A host directory wouldn't be available on all potential 171 >hosts. 172 173 ### Mount a shared-storage volume as a data volume 174 175 In addition to mounting a host directory in your container, some Docker 176 [volume plugins](../extend/plugins_volume.md) allow you to 177 provision and mount shared storage, such as iSCSI, NFS, or FC. 178 179 A benefit of using shared volumes is that they are host-independent. This 180 means that a volume can be made available on any host that a container is 181 started on as long as it has access to the shared storage backend, and has 182 the plugin installed. 183 184 One way to use volume drivers is through the `docker run` command. 185 Volume drivers create volumes by name, instead of by path like in 186 the other examples. 187 188 The following command creates a named volume, called `my-named-volume`, 189 using the `flocker` volume driver, and makes it available within the container 190 at `/opt/webapp`: 191 192 ```bash 193 $ docker run -d -P \ 194 --volume-driver=flocker \ 195 -v my-named-volume:/opt/webapp \ 196 --name web training/webapp python app.py 197 ``` 198 199 You may also use the `docker volume create` command, to create a volume before 200 using it in a container. 201 202 The following example also creates the `my-named-volume` volume, this time 203 using the `docker volume create` command. 204 205 ```bash 206 $ docker volume create -d flocker --name my-named-volume -o size=20GB 207 208 $ docker run -d -P \ 209 -v my-named-volume:/opt/webapp \ 210 --name web training/webapp python app.py 211 ``` 212 213 A list of available plugins, including volume plugins, is available 214 [here](../extend/plugins.md). 215 216 ### Volume labels 217 218 Labeling systems like SELinux require that proper labels are placed on volume 219 content mounted into a container. Without a label, the security system might 220 prevent the processes running inside the container from using the content. By 221 default, Docker does not change the labels set by the OS. 222 223 To change a label in the container context, you can add either of two suffixes 224 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 225 objects on the shared volumes. The `z` option tells Docker that two containers 226 share the volume content. As a result, Docker labels the content with a shared 227 content label. Shared volume labels allow all containers to read/write content. 228 The `Z` option tells Docker to label the content with a private unshared label. 229 Only the current container can use a private volume. 230 231 ### Mount a host file as a data volume 232 233 The `-v` flag can also be used to mount a single file - instead of *just* 234 directories - from the host machine. 235 236 ```bash 237 $ docker run --rm -it -v ~/.bash_history:/root/.bash_history ubuntu /bin/bash 238 ``` 239 240 This will drop you into a bash shell in a new container, you will have your bash 241 history from the host and when you exit the container, the host will have the 242 history of the commands typed while in the container. 243 244 > **Note:** 245 > Many tools used to edit files including `vi` and `sed --in-place` may result 246 > in an inode change. Since Docker v1.1.0, this will produce an error such as 247 > "*sed: cannot rename ./sedKdJ9Dy: Device or resource busy*". In the case where 248 > you want to edit the mounted file, it is often easiest to instead mount the 249 > parent directory. 250 251 ## Creating and mounting a data volume container 252 253 If you have some persistent data that you want to share between 254 containers, or want to use from non-persistent containers, it's best to 255 create a named Data Volume Container, and then to mount the data from 256 it. 257 258 Let's create a new named container with a volume to share. 259 While this container doesn't run an application, it reuses the `training/postgres` 260 image so that all containers are using layers in common, saving disk space. 261 262 ```bash 263 $ docker create -v /dbdata --name dbstore training/postgres /bin/true 264 ``` 265 266 You can then use the `--volumes-from` flag to mount the `/dbdata` volume in another container. 267 268 ```bash 269 $ docker run -d --volumes-from dbstore --name db1 training/postgres 270 ``` 271 272 And another: 273 274 ```bash 275 $ docker run -d --volumes-from dbstore --name db2 training/postgres 276 ``` 277 278 In this case, if the `postgres` image contained a directory called `/dbdata` 279 then mounting the volumes from the `dbstore` container hides the 280 `/dbdata` files from the `postgres` image. The result is only the files 281 from the `dbstore` container are visible. 282 283 You can use multiple `--volumes-from` parameters to combine data volumes from 284 several containers. To find detailed information about `--volumes-from` see the 285 [Mount volumes from container](../reference/commandline/run.md#mount-volumes-from-container-volumes-from) 286 in the `run` command reference. 287 288 You can also extend the chain by mounting the volume that came from the 289 `dbstore` container in yet another container via the `db1` or `db2` containers. 290 291 ```bash 292 $ docker run -d --name db3 --volumes-from db1 training/postgres 293 ``` 294 295 If you remove containers that mount volumes, including the initial `dbstore` 296 container, or the subsequent containers `db1` and `db2`, the volumes will not 297 be deleted. To delete the volume from disk, you must explicitly call 298 `docker rm -v` against the last container with a reference to the volume. This 299 allows you to upgrade, or effectively migrate data volumes between containers. 300 301 > **Note:** Docker will not warn you when removing a container *without* 302 > providing the `-v` option to delete its volumes. If you remove containers 303 > without using the `-v` option, you may end up with "dangling" volumes; 304 > volumes that are no longer referenced by a container. 305 > You can use `docker volume ls -f dangling=true` to find dangling volumes, 306 > and use `docker volume rm <volume name>` to remove a volume that's 307 > no longer needed. 308 309 ## Backup, restore, or migrate data volumes 310 311 Another useful function we can perform with volumes is use them for 312 backups, restores or migrations. You do this by using the 313 `--volumes-from` flag to create a new container that mounts that volume, 314 like so: 315 316 ```bash 317 $ docker run --rm --volumes-from dbstore -v $(pwd):/backup ubuntu tar cvf /backup/backup.tar /dbdata 318 ``` 319 320 Here you've launched a new container and mounted the volume from the 321 `dbstore` container. You've then mounted a local host directory as 322 `/backup`. Finally, you've passed a command that uses `tar` to backup the 323 contents of the `dbdata` volume to a `backup.tar` file inside our 324 `/backup` directory. When the command completes and the container stops 325 we'll be left with a backup of our `dbdata` volume. 326 327 You could then restore it to the same container, or another that you've made 328 elsewhere. Create a new container. 329 330 ```bash 331 $ docker run -v /dbdata --name dbstore2 ubuntu /bin/bash 332 ``` 333 334 Then un-tar the backup file in the new container`s data volume. 335 336 ```bash 337 $ docker run --rm --volumes-from dbstore2 -v $(pwd):/backup ubuntu bash -c "cd /dbdata && tar xvf /backup/backup.tar --strip 1" 338 ``` 339 340 You can use the techniques above to automate backup, migration and 341 restore testing using your preferred tools. 342 343 ## Removing volumes 344 345 A Docker data volume persists after a container is deleted. You can create named 346 or anonymous volumes. Named volumes have a specific source form outside the 347 container, for example `awesome:/bar`. Anonymous volumes have no specific 348 source. When the container is deleted, you should instruct the Docker Engine daemon 349 to clean up anonymous volumes. To do this, use the `--rm` option, for example: 350 351 ```bash 352 $ docker run --rm -v /foo -v awesome:/bar busybox top 353 ``` 354 355 This command creates an anonymous `/foo` volume. When the container is removed, 356 the Docker Engine removes the `/foo` volume but not the `awesome` volume. 357 358 ## Important tips on using shared volumes 359 360 Multiple containers can also share one or more data volumes. However, multiple 361 containers writing to a single shared volume can cause data corruption. Make 362 sure your applications are designed to write to shared data stores. 363 364 Data volumes are directly accessible from the Docker host. This means you can 365 read and write to them with normal Linux tools. In most cases you should not do 366 this as it can cause data corruption if your containers and applications are 367 unaware of your direct access. 368 369 # Next steps 370 371 Now you've learned a bit more about how to use Docker we're going to see how to 372 combine Docker with the services available on 373 [Docker Hub](https://hub.docker.com) including Automated Builds and private 374 repositories. 375 376 Go to [Store images in Docker Hub](dockerrepos.md).