Al trabajar con Docker, es común encontrarse con desafíos al intentar levantar servicios. Uno de los problemas recurrentes, especialmente para quienes se inician, es que un contenedor MySQL reporte un estado de "unhealthy" (no saludable) o simplemente falle al iniciar. Este estado indica que, aunque el contenedor esté en ejecución, el servicio principal dentro de él no está funcionando como se espera o no ha pasado las comprobaciones de salud definidas.

A continuación, exploramos las causas más frecuentes de estos fallos y cómo abordarlas, facilitando el despliegue de bases de datos MySQL en entornos Docker.

1. Tiempos de Espera Excedidos en las Verificaciones de Salud

MySQL, al iniciarse por primera vez o después de una reconfiguración, requiere tiempo para la inicialización del esquema de datos o la aplicación de migraciones. Los chequeos de salud por defecto de Docker pueden ser demasiado restrictivos y marcar el contenedor como "no saludable" antes de que MySQL esté completamente operativo.

Solución: Ajustar los parámetros de HEALTHCHECK en su archivo docker-compose.yml para otorgar más tiempo. Puede modificar el intervalo, el tiempo de espera y el número de reintentos:

version: '3.8'
services:
  mysql_db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: example_password
      MYSQL_DATABASE: mydatabase
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-pexample_password"]
      interval: 10s       # Chequear cada 10 segundos
      timeout: 30s        # Esperar hasta 30 segundos por respuesta
      retries: 5          # Reintentar 5 veces antes de fallar
      start_period: 60s   # Esperar 60 segundos antes de iniciar los chequeos

El parámetro start_period es crucial para permitir que MySQL se iniicalice antes de que comiencen las verificaciones activas.

2. Asignación Insuficiente de Memoria

MySQL es un sistema de gestión de bases de datos que puede consumir una cantidad considerable de memoria, especialmente durante el arranque y la inicialización. Si el contenedor se ejecuta con una asignación de memoria demasiado baja, es probable que falle al iniciar o que sea terminado abruptamente por el sistema operativo (Out Of Memory - OOM).

Solución: Asegúrese de asignar suficiente memoria RAM a su contenedor MySQL. Una base de datos pequeña podría requerir al menos 512 MB, mientras que entornos más demandantes necesitarán gigabytes. Defina el límite de memoria en docker-compose.yml:

version: '3.8'
services:
  mysql_db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: example_password
      MYSQL_DATABASE: mydatabase
    deploy:
      resources:
        limits:
          memory: 1024M # Asignar 1 GB de RAM

Ajuste este valor según sus necesidades, pero evite asignaciones excesivamente bajas.

3. Problemas de Permisos en Volúmenes de Datos

Cuando se montan directorios locales (bind mounts) como volúmenes para los datos de MySQL, es común que surjan problemas de permisos. El usuario mysql dentro del contenedor necesita tener derechos de lectura y escritura sobre el directorio de datos montado en el host. Si los permisos no son correctos, MySQL no podrá crear o acceder a sus archivos de datos.

Solución: Verifique y ajuste los permisos del directorio en el sistema anfitrión. Puede hacerlo utilizando chmod y chown para que el usuario o grupo mysql (o su UID/GID correspondiente, típicamente 999 o 1000 dependiendo de la imagen base) tenga acceso.

sudo chown -R 999:999 /ruta/a/sus/datos/mysql  # Reemplace 999 por el UID/GID de mysql
sudo chmod -R 755 /ruta/a/sus/datos/mysql

Alternativamente, utilice volúmenes gestionados por Docker (named volumes), que Docker maneja internamente, evitando estos problemas de permisos del host.

version: '3.8'
services:
  mysql_db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: example_password
      MYSQL_DATABASE: mydatabase
    volumes:
      - mysql_data:/var/lib/mysql # Uso de un volumen con nombre
volumes:
  mysql_data:

4. Conflictos en Archivos de Configuración Personalizados

Si está utilizando un archivo my.cnf personalizado para configurar MySQL, es posible que contenga parámetros que entren en conflicto con la configuración predeterminada de la imagen de Docker, o que apunten a rutas inexistentes dentro del contenedor.

Solución: Comience con una configuración básica. Primero, inicie el contenedor MySQL sin ningún archivo my.cnf personalizado para asegurarse de que la imagen base funciona correctamente. Una vez confirmado el arranque exitoso, añada sus configuraciones personalizadas de forma incremental, monitoreando los logs del contenedor (docker logs <nombre_contenedor>) para identificar cualquier error.

Si necesita usar un archivo my.cnf, asegúrese de montarlo correctamente y de que sus rutas internas sean válidas dentro del contenedor:

version: '3.8'
services:
  mysql_db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: example_password
      MYSQL_DATABASE: mydatabase
    volumes:
      - ./config/my-custom.cnf:/etc/mysql/conf.d/my-custom.cnf # Montar un archivo de config

5. Conflicto de Puertos en el Anfitrión

El puerto predeterminado para MySQL es 3306. Si ya hay otro servicio (otra instancia de MySQL, un servidor web, etc.) utilizando este puerto en su máquina anfitriona, el contenedor MySQL no podrá asignar el puerto y fallará al iniciar.

Solución: Verifique si el puerto 3306 está siendo utilizado en su sistema anfitrión. En Linux o macOS, puede usar:

sudo netstat -tulpn | grep 3306
# O para macOS
sudo lsof -i :3306

Si el puerto está ocupado, tiene dos opciones: detener el servicio que lo está usando o, más comúnmente, mapear el puerto del contenedor a un puerto diferente en el anfitrión en su docker-compose.yml:

version: '3.8'
services:
  mysql_db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example_password
      MYSQL_DATABASE: mydatabase
    ports:
      - "3307:3306" # Mapea el puerto 3306 del contenedor al puerto 3307 del anfitrión

Con estas soluciones, podrá diagnosticar y resolver la mayoría de los problemas de arranque que encuentre con sus contenedores MySQL en Docker.