¿Cómo usar Docker Compose en un VPS Ubuntu o Debian?
Escribir un archivo compose.yaml, lanzar WordPress y MariaDB con docker compose up -d y después gestionar registros, actualizaciones, copias de seguridad y
Docker Compose describe varios contenedores en un solo archivo, compose.yaml: imágenes, puertos, volúmenes, variables y orden de arranque. Un único comando, docker compose up -d, crea o actualiza toda la pila. Esta guía parte de un VPS con Docker ya instalado, monta un ejemplo concreto, WordPress con MariaDB, y luego detalla los comandos del día a día y los errores más frecuentes. Se aplica tal cual a Ubuntu 22.04 / 24.04 y a Debian 12 / 13.
Procedimiento paso a paso
-
Comprobar Docker y el plugin Compose
Ejecute docker compose version. Si la respuesta es docker: 'compose' is not a docker command, instale Docker desde el repositorio oficial con el paquete docker-compose-plugin, como en la guía de instalación de Docker.
-
Crear la carpeta del proyecto
Cree una carpeta por aplicación, por ejemplo /opt/wordpress, y sitúese en ella. Compose da al proyecto el nombre de esta carpeta y busca compose.yaml en la carpeta actual.
-
Escribir el archivo .env y compose.yaml
Genere una contraseña en .env, legible solo por root, y copie el archivo compose.yaml de abajo. Al arrancar, Compose sustituye ${DB_PASSWORD} por el valor leído en .env.
-
Arrancar la pila
Ejecute docker compose up -d. Compose descarga las imágenes, crea la red y los volúmenes, espera a que MariaDB esté lista y arranca WordPress. Después, docker compose ps muestra los dos servicios en Up, con (healthy) para db.
-
Probar y leer los registros
Desde el VPS, curl -I http://127.0.0.1:8080 debe devolver una redirección a la página de instalación de WordPress. Si algo falla, docker compose logs -f --tail=100 muestra los registros de todos los servicios.
-
Actualizar los contenedores
Para pasar a una nueva versión, cambie la etiqueta de la imagen en compose.yaml y ejecute docker compose pull y docker compose up -d: solo se recrean los contenedores cuya imagen o configuración ha cambiado, y los volúmenes se mantienen.
Crear el proyecto y su contraseña
mkdir -p /opt/wordpress
cd /opt/wordpress
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env
Archivo compose.yaml: WordPress y MariaDB
services:
db:
image: mariadb:11.4
restart: unless-stopped
environment:
MARIADB_DATABASE: wordpress
MARIADB_USER: wordpress
MARIADB_PASSWORD: ${DB_PASSWORD}
MARIADB_RANDOM_ROOT_PASSWORD: "1"
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 5
wordpress:
image: wordpress:6.8-apache
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
WORDPRESS_DB_NAME: wordpress
ports:
- "127.0.0.1:8080:80"
volumes:
- wp_data:/var/www/html
volumes:
db_data:
wp_data:
Arrancar y comprobar
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs -f --tail=100
Comandos de Docker Compose del día a día
docker compose ps
docker compose logs --tail=50 wordpress
docker compose restart wordpress
docker compose exec db sh
docker compose stop
docker compose start
docker compose down
docker compose config --quiet
docker compose ls
Actualizar las imágenes
cd /opt/wordpress
docker compose pull
docker compose up -d
docker image prune -f
Hacer una copia de la base MariaDB
cd /opt/wordpress
docker compose exec -T db sh -c 'mariadb-dump -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > wordpress-$(date +%F).sql
HTTPS con Caddy: compose.override.yaml
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
Caddyfile
example.com {
reverse_proxy wordpress:80
}
Antes de empezar
Necesita un VPS Linux con Docker Engine y el plugin Compose, instalados desde el repositorio oficial de Docker: siga la guía «¿Cómo instalar Docker en Debian 12 o Ubuntu 24.04?» si aún no lo ha hecho. Los comandos se ejecutan como root; una cuenta del grupo docker también puede ejecutarlos sin sudo.
- Compose v2 se escribe docker compose, con un espacio. El antiguo programa docker-compose (v1) no se mantiene desde 2023: no lo instale ni con pip ni con apt.
- El archivo se llama compose.yaml; docker-compose.yml se sigue leyendo en los proyectos antiguos. La línea version: al principio del archivo está obsoleta y ya no sirve para nada.
- WordPress y MariaDB caben en 1 a 2 GB de RAM; prevea más en cuanto funcionen varias pilas en el mismo VPS.
Entender el archivo compose.yaml
Cada entrada de services se convierte en un contenedor. Compose también crea una red privada para el proyecto: los servicios se comunican en ella por su nombre, de ahí WORDPRESS_DB_HOST: db. No se publica ningún puerto de MariaDB, así que la base de datos sigue siendo invisible desde Internet.
- image: la imagen y su etiqueta. Fije una versión (mariadb:11.4) en lugar de latest para saber qué está actualizando.
- ports: "127.0.0.1:8080:80" publica el puerto 80 del contenedor en el puerto 8080 del VPS, solo en local. Sin 127.0.0.1, el puerto queda abierto a Internet, aunque UFW lo bloquee.
- volumes: un volumen con nombre (db_data) conserva los datos cuando se recrea el contenedor. Solo se elimina con docker compose down -v o docker volume rm.
- environment y .env: los secretos se quedan en .env, fuera del archivo que comparte o versiona.
- restart: unless-stopped vuelve a lanzar los contenedores tras un fallo o un reinicio del VPS, salvo los que haya detenido a mano.
- depends_on con condition: service_healthy espera a que el healthcheck de MariaDB tenga éxito antes de arrancar WordPress.
Publicar el sitio en HTTPS
Para servir el sitio con un nombre de dominio, apunte un registro A a la IPv4 del VPS, abra los puertos 80 y 443 y añada Caddy en un archivo compose.override.yaml, que Compose lee automáticamente junto con compose.yaml. Sustituya example.com por su dominio en el Caddyfile: Caddy obtiene y renueva solo el certificado de Let’s Encrypt.
Termine después la instalación de WordPress desde la dirección https de su dominio, no desde 127.0.0.1: WordPress guarda la dirección usada durante la instalación.
Copias de seguridad y actualizaciones del stack
Un volumen no es una copia de seguridad: desaparece con el VPS o con un down -v lanzado por error. Exporte la base de datos con mariadb-dump (bloque de arriba), copie la carpeta del proyecto y el contenido de los volúmenes y envíelo todo fuera del VPS.
- docker compose pull descarga las nuevas imágenes de las etiquetas indicadas, docker compose up -d recrea los contenedores afectados y docker image prune -f libera el espacio de las imágenes antiguas.
- Antes de cambiar de versión principal de MariaDB o PostgreSQL, haga una exportación SQL: la nueva versión puede exigir una migración de los datos.
- docker system df indica el espacio que ocupan las imágenes, los contenedores y los volúmenes.
¿Qué VPS elegir para Docker Compose?
Docker necesita un kernel Linux real: un VPS KVM sirve, un alojamiento compartido no. En ACLClouds, a 16 de noviembre de 2026, el VPS Mini (2 vCPU, 8 GB de RAM, 40 GB de almacenamiento) cuesta 4,99 € al mes sin permanencia, o 3,99 € al mes con un compromiso de un año: mueve varias pilas Compose pequeñas. El VPS Essentiel (4 vCPU, 16 GB de RAM, 80 GB), a 9,99 € al mes, es adecuado para una base de datos con mucha carga o para n8n junto a un sitio web.
La opción -v de docker compose down borra los datos
docker compose down -v también elimina los volúmenes con nombre del proyecto, es decir, la base de datos MariaDB y los archivos de WordPress. Haga una exportación antes de cualquier comando con -v.
Verificación rápida
- docker compose version responde sin errores.
- docker compose ps muestra db en (healthy) y wordpress en Up.
- El puerto 8080 solo está publicado en 127.0.0.1.
- .env tiene el modo 600 y no está en ningún repositorio Git.
- Hay una exportación SQL reciente guardada fuera del VPS.
Preguntas frecuentes
¿Por qué aparece no configuration file provided: not found?
Compose no encuentra ni compose.yaml ni docker-compose.yml en la carpeta actual. Sitúese en la carpeta del proyecto con cd /opt/wordpress, o indique el archivo con docker compose -f /opt/wordpress/compose.yaml up -d.
Compose muestra «the attribute version is obsolete», ¿es grave?
No, es solo un aviso. Compose v2 ignora la línea version: "3.8" al principio del archivo: bórrela para que desaparezca, el resto del archivo no cambia.
¿Por qué aparece port is already allocated o address already in use al arrancar?
Otro contenedor ya publica ese puerto, o un servicio del VPS (nginx, Apache) lo está escuchando. Localícelo con docker ps --filter publish=80 y ss -tlnp | grep :80, y luego deténgalo o cambie el puerto de la izquierda en ports, por ejemplo "8081:80".
¿Por qué aparece docker: 'compose' is not a docker command?
El plugin Compose v2 no está instalado. Con el repositorio oficial de Docker, ejecute apt install docker-compose-plugin. Los paquetes docker.io y docker-compose de las distribuciones van con retraso o solo ofrecen el antiguo comando con guion.
¿Por qué no se aplican mis cambios en compose.yaml?
docker compose restart reinicia los contenedores sin volver a leer el archivo. Ejecute docker compose up -d: Compose compara la configuración y recrea los servicios modificados. Compruebe antes el archivo con docker compose config.
¿Han desaparecido mis datos después de docker compose down?
No: docker compose down elimina los contenedores y la red, no los volúmenes con nombre. Los datos solo desaparecen con down -v, o si se escribían dentro del contenedor sin volumen. docker volume ls lista los volúmenes, con el nombre del proyecto como prefijo, por ejemplo wordpress_db_data.
¿Qué hay que corregir tras yaml: line 8: mapping values are not allowed in this context?
El archivo YAML está mal sangrado: un tabulador en lugar de espacios, o un nivel desplazado. Use solo espacios (dos por nivel), ponga entre comillas los valores que contienen :, como los puertos, y compruébelo con docker compose config.