Curso de MariaDB / Crear un entorno local con Docker Compose
Docker Compose permite definir un contenedor MariaDB, su puerto de conexión y su almacenamiento persistente en un archivo. Proporciona un entorno de aprendizaje separado sin instalar un servicio de base de datos en el equipo, pero eliminar el contenedor y eliminar su volumen de datos tienen consecuencias distintas.
Definir el entorno y comprobar los requisitos
Docker ejecuta aplicaciones en contenedores y Compose describe su configuración mediante YAML. Este ejemplo inicia una base y publica 127.0.0.1:3307 en el equipo. Un puerto distinto permite coexistir con un servidor que ya utilice 3306. La guía de conexiones locales y remotas ayuda a distinguir las rutas, y la práctica de copias de seguridad explica qué debe conservar aparte del volumen.
Instale Docker Engine con el complemento Compose o Docker Desktop siguiendo las instrucciones oficiales de Compose. En Windows utilice contenedores Linux. Inicie el motor y compruebe en una terminal que funcionan ambos comandos antes de preparar la base:
docker version
docker compose version
La configuración utiliza expresamente la familia de imagen mariadb:11.8. Esa etiqueta puede apuntar a una revisión de mantenimiento más reciente; si necesita reproducción exacta, registre una etiqueta de revisión o un digest aprobado, el identificador de contenido de la imagen. La comprobación de sintaxis y de SQL no sustituye probar el arranque, la salud y la persistencia del volumen en su entorno Docker.
Crear el proyecto y los archivos de contraseñas
- Cree una carpeta nueva
mariadb-appopsy abra en ella la terminal. No ejecute estos comandos desde otro proyecto Compose. - Cree una subcarpeta
secretscon los archivos UTF-8root-password.txtyapp-password.txt. Guarde una contraseña distinta en cada archivo, sin dejarlos vacíos ni añadir explicaciones. - Guarde la configuración completa del apartado siguiente como
compose.yaml. Cree también un archivo.gitignorecon las dos líneas siguientes y restrinja el acceso a las contraseñas.
secrets/
.env
Los secretos de Compose proporcionan archivos a servicios seleccionados; no convierten los archivos originales locales en una caja fuerte cifrada. Proteja tanto los archivos como el acceso a Docker. La documentación oficial de secretos de Compose explica los montajes y el requisito de contenedores Linux.
Entender la configuración completa de Compose
name: mariadb-appops
services:
db:
image: mariadb:11.8
ports:
- "127.0.0.1:3307:3306"
environment:
MARIADB_ROOT_PASSWORD_FILE: /run/secrets/root_password
MARIADB_DATABASE: appops_lab
MARIADB_USER: app_user
MARIADB_PASSWORD_FILE: /run/secrets/app_password
secrets:
- root_password
- app_password
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
secrets:
root_password:
file: ./secrets/root-password.txt
app_password:
file: ./secrets/app-password.txt
volumes:
db_data:
El equipo publica el puerto 3307 y MariaDB utiliza 3306 dentro del contenedor. Un cliente del equipo se conecta a 127.0.0.1:3307; otro servicio de la misma red Compose utiliza db:3306. Publicar en la dirección de loopback limita este punto de acceso del ejemplo al equipo local.
El volumen con nombre db_data guarda el directorio de datos. Las variables terminadas en _FILE indican archivos de contraseñas. La referencia oficial de variables de la imagen MariaDB explica la inicialización de una base, un usuario y sus contraseñas cuando el directorio de datos es nuevo. Editar el archivo de contraseña no cambia por sí solo una cuenta ya almacenada en un volumen inicializado.
El script oficial healthcheck.sh comprueba la conexión y la inicialización de InnoDB. Que el contenedor esté en ejecución no demuestra por sí solo que MariaDB esté listo para las consultas del ejercicio.
Iniciar el servicio y comprobar una fila almacenada
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=80 db
El primer comando valida la configuración con Compose. Compruebe que el servicio alcanza el estado healthy y revise el registro de inicialización si no lo hace. Corrija rutas de secretos inexistentes o un puerto ocupado antes de reintentar. Evite compartir registros sin revisar si contienen información sensible.
docker compose exec db mariadb --default-character-set=utf8mb4 -u app_user -p appops_lab
Introduzca la contraseña de app-password.txt cuando se solicite. Dentro del cliente SQL, ejecute el bloque completo siguiente; devuelve una fila. La creación es para la primera ejecución: si la tabla existe, inspeccione las prácticas anteriores en lugar de repetir a ciegas la preparación.
USE appops_lab;
CREATE TABLE docker_notes (
note_id INT NOT NULL PRIMARY KEY,
note_text VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO docker_notes VALUES (1, 'volume survives container replacement');
SELECT note_id, note_text FROM docker_notes;
El texto inglés guardado en la fila significa «el volumen sobrevive a la sustitución del contenedor» y se conserva como literal del ejercicio. Su presencia después de recrear el contenedor será la comprobación de persistencia.
Si el equipo tiene instalado un cliente mariadb, este comando llega al mismo servidor por el puerto publicado. Utilizar 3306 aquí podría dirigirlo a otra base local:
mariadb --protocol=tcp --host=127.0.0.1 --port=3307 --default-character-set=utf8mb4 -u app_user -p appops_lab
Sustituir el contenedor conservando el volumen
docker compose down
docker compose up -d
En esta configuración, down sin opciones elimina los contenedores y la red del proyecto y mantiene el volumen de datos con nombre. Cuando el servicio nuevo esté healthy, vuelva a conectar y ejecute SELECT * FROM docker_notes;. La fila insertada debe seguir presente: leerla comprueba la persistencia en lugar de darla por supuesta.
docker compose down --volumes elimina también volúmenes y puede descartar la base. No es un comando de reinicio ordinario. Úselo únicamente después de confirmar que los datos de prácticas del proyecto son prescindibles. Un volumen no es una copia de seguridad; siga el procedimiento de copia de la base para datos que deba conservar. La referencia oficial de Compose down detalla qué elimina.
Diagnosticar antes de reinicializar los datos
| Síntoma | Qué comprobar |
|---|---|
| No se puede contactar con el motor Docker | Docker Desktop o Engine en ejecución y contexto Docker seleccionado |
| Puerto publicado ocupado | Puerto 3307 del equipo; si cambia, cambie también el puerto del cliente |
| Access denied | Cuenta y contraseña de la inicialización y existencia previa del volumen |
| Contenedor ejecutándose sin SQL disponible | Salud, registro de inicialización y diferencia entre db en la red y 127.0.0.1 en el equipo |
| Datos inesperados tras recrear | Proyecto mariadb-appops, carpeta de trabajo, puerto y volumen montado |
No elimine el volumen como primera medida de diagnóstico. Identifique el servidor y el directorio de datos utilizados y decida si necesita corregir la configuración o realizar deliberadamente una inicialización nueva.




