Volumes in Compose in Docker - Commands & Configuration

Introduction

Sometimes your app needs to save data that stays safe even if the app stops or restarts. Volumes in Docker Compose help you keep this data outside the app container so it doesn't get lost.

When you want to save database files so they are not deleted when the container stops.

When you need to share files between your computer and the app running inside a container.

When you want to keep logs or uploads safe even if you update or remove the app container.

When multiple containers need to access the same files or data.

When you want to separate app code from data for easier backups and updates.

Config File - docker-compose.yml

docker-compose.yml

version: '3.9'
services:
  web:
    image: nginx:1.23
    volumes:
      - web-data:/usr/share/nginx/html
volumes:
  web-data:
    driver: local

This file defines a service named web using the nginx image.

The volumes section inside the service maps a named volume web-data to the container path /usr/share/nginx/html, where nginx serves files.

The volumes key at the bottom declares the named volume web-data using the local driver, which stores data on the host machine.

Commands

This command starts the services defined in the docker-compose.yml file in detached mode, creating the volume automatically if it does not exist.

Terminal

docker-compose up -d

Expected Output

Creating network "default" with the default driver

Creating volume "web-data" with local driver

Creating compose_web_1 ... done

→

-d - Run containers in the background (detached mode)

This command lists all Docker volumes on your system, so you can verify that the named volume was created.

Terminal

docker volume ls

Expected Output

DRIVER    VOLUME NAME

local     web-data

This command stops and removes the containers and network created by docker-compose up, but it keeps the volume data safe.

Terminal

docker-compose down

Expected Output

Stopping compose_web_1 ... done

Removing compose_web_1 ... done

Removing network default

This command shows detailed information about the named volume, including where the data is stored on your host machine.

Terminal

docker volume inspect web-data

Expected Output

[

    {

        "CreatedAt": "2024-06-01T12:00:00Z",

        "Driver": "local",

        "Labels": null,

        "Mountpoint": "/var/lib/docker/volumes/web-data/_data",

        "Name": "web-data",

        "Options": null,

        "Scope": "local"

    }

]

Key Concept

If you remember nothing else from this pattern, remember: volumes keep your app data safe outside containers so it persists across restarts and updates.

Common Mistakes

Not declaring the named volume under the top-level volumes key in docker-compose.yml.

Docker Compose will create an anonymous volume instead, making it harder to manage or reuse the data.

Always declare named volumes explicitly under the volumes section at the bottom of the compose file.

Using a relative host path instead of a named volume for persistent data.

Relative paths can cause permission issues or data loss if the path is not correct or shared properly.

Use named volumes for data that needs to persist and be managed by Docker.

Running docker-compose down with the --volumes flag expecting data to be kept.

The --volumes flag deletes all volumes created by the compose file, causing data loss.

Run docker-compose down without --volumes to keep your data safe.

Summary

Define named volumes in docker-compose.yml to store persistent data outside containers.

Use docker-compose up -d to start services and create volumes automatically.

Use docker volume ls and docker volume inspect to check and manage your volumes.

Use docker-compose down without --volumes to stop containers but keep data safe.