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 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:

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.

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.