Create volumes.md

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/<an_image>
+```
+
+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.