Entendiendo los Volúmenes Docker

Los contenedores Docker son efímeros por diseño. Cuando un contenedor se detiene y elimina, todos los datos escritos dentro del sistema de archivos del contenedor se pierden. Esta es una característica, no un error — asegura que los contenedores sean reproducibles y sin estado. Pero la mayoría de las aplicaciones del mundo real necesitan datos persistentes: bases de datos, archivos subidos, configuración, logs.

Docker proporciona tres mecanismos para la persistencia de datos:

  1. Volúmenes Nombrados: Gestionados por Docker, almacenados en /var/lib/docker/volumes/. El enfoque recomendado para la mayoría de casos de uso.
  2. Bind Mounts: Mapean un directorio específico del host al contenedor. Útiles para desarrollo pero requieren gestión cuidadosa de permisos.
  3. Montajes tmpfs: Almacenamiento en memoria que se descarta cuando el contenedor se detiene.

Requisitos Previos

  • Docker Engine 20.10+ instalado en Linux, macOS o Windows con WSL2.
  • Acceso shell al host Docker.
  • Familiaridad básica con comandos CLI de Docker (docker run, docker inspect, docker volume).

Problemas Comunes de Volúmenes Docker

1. Pérdida de Datos al Reiniciar el Contenedor

Síntoma: Sus datos de base de datos o aplicación desaparecen cada vez que recrea el contenedor.

Causa: No hay ningún volumen montado. Los datos se escriben en la capa escribible del contenedor que se elimina con el contenedor.

Solución: Siempre monte un volumen nombrado para datos persistentes:

docker volume create myapp-data

docker run -d \
  --name postgres-db \
  -v myapp-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

Para Docker Compose:

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:
    driver: local

Crítico: Si usa docker-compose down -v, la flag -v eliminará todos los volúmenes. Use docker-compose down sin -v para conservar sus datos.

2. Errores de Permiso Denegado

Síntoma: Los logs del contenedor muestran Permission denied al intentar leer o escribir archivos en un volumen montado.

Pasos de diagnóstico:

docker exec mycontainer id
ls -lan /ruta/al/directorio/host
docker exec mycontainer ls -lan /data

Soluciones:

A) Use un volumen nombrado:

docker run -d -v myvolume:/data myimage

B) Coincida el UID con --user:

docker run -d --user "$(id -u):$(id -g)" -v ./data:/data myimage

C) Corrija la propiedad en el entrypoint:

COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

3. Bind Mount Muestra Directorio Vacío

Síntoma: Después de montar un directorio del host, el contenedor ve un directorio vacío.

Causa: Los bind mounts sobreescriben el sistema de archivos del contenedor.

Solución: Use volúmenes nombrados. Docker copia el contenido de la imagen al volumen en el primer uso:

# Volumen nombrado — contenido preservado
docker run -d -v myvolume:/usr/share/nginx/html nginx

# Bind mount — reemplaza contenido (vacío si el dir del host está vacío)
docker run -d -v ./empty-dir:/usr/share/nginx/html nginx

4. Volúmenes Huérfanos Consumiendo Espacio en Disco

docker volume ls -f dangling=true
docker system df
docker volume prune

Advertencia: docker volume prune -a eliminará volúmenes nombrados también si ningún contenedor los referencia.

5. Datos del Volumen No Se Sincronizan en macOS/Windows

Causa: Docker Desktop ejecuta contenedores dentro de una VM Linux. Los bind mounts pasan por una capa de compartición de archivos.

Soluciones:

  • Use VirtioFS (Docker Desktop 4.15+): Habilítelo en la configuración de Docker Desktop.
  • Use volúmenes nombrados para conjuntos de datos grandes.
  • Use docker-compose watch (Compose 2.22+).

Prevención y Mejores Prácticas

  • Siempre use volúmenes nombrados para bases de datos y servicios con estado.
  • Nunca use docker-compose down -v en producción.
  • Respalde volúmenes regularmente.
  • Etiquete sus volúmenes para organización.
  • Configure montajes de solo lectura donde sea posible usando el sufijo :ro.

Resumen

  • Los contenedores Docker son efímeros — siempre use volúmenes para datos persistentes.
  • Los errores de permiso surgen de desajustes de UID entre el proceso del contenedor y la ruta montada.
  • Los volúmenes nombrados son preferidos sobre bind mounts en producción.
  • Limpie volúmenes huérfanos con docker volume prune para recuperar espacio en disco.

Artículos Relacionados