diff --git a/general/volumes.md b/general/volumes.md new file mode 100644 index 000000000..7010f7ba2 --- /dev/null +++ b/general/volumes.md @@ -0,0 +1,25 @@ +# Volumes + +In Docker terminology, a _volume_ is a storage device that allows you to persist the data used and generated by each of your running containers. While a container remains alive (in either an active or inactive state), the data inside its user-space remains intact. However, if you decide to recreate a container, all data within that container is lost. Volumes are an intrinsic aspect of container management, so it is useful to know how to create them. + +There are two ways to map persistent storage to your containers; container volumes, and directory overlays. All of our images reference persistent data by means of directory overlays. + +## Mapping a volume to your container + +Firstly, you must understand which directories from _within_ your container you wish to persist. All of our images come with side-by-side documentation on which internal directories are used by the application. As mentioned in the [Running our Containers](/docs/running-our-containers) documentation, the most common directory you will wish to persist is the `/config` directory. + +Before you create your container, first create a directory on the host machine that will act as the home for your persisted data. We recommend creating the directory `/opt/appdata`. Under this tree, you can create a single configuration directory for each of your containers. + +When creating the container itself, now is the time to make use of the `-v` flag, which will tell Docker to overlay your host directory over the container's directory: + +```bash{2} +docker create --name my_container \ + -v /opt/appdata/my_config:/config \ + linuxserver/ +``` + +The above example shows how the usage of `-v` has mapped the host machine's `/opt/appdata/my_config` directory over the container's internal `/config` directory. + +> **Remember**: When dealing with mapping overlays, it always reads `host:container` + +You can do this for as many directories as required by either you or the container itself. Our rule-of-thumb is to _always_ map the `/config` directory as this contains pertinent runtime configuration for the underlying application. For applications that require further data, such as media, our documentation will clearly indicate which internal directories need mapping.