Contenedores
Docker y Docker Compose en Ubuntu y Debian: instalación y primer despliegue
Instala Docker y Docker Compose en Ubuntu y Debian, entiende imágenes, contenedores, volúmenes y redes, y despliega un stack con base de datos paso a paso.

Docker empaqueta una aplicación y todo lo que necesita para correr (runtime, librerías, configuración) en una unidad que se ejecuta igual en tu portátil, en el servidor de staging y en producción. Docker Compose describe en un solo archivo varios de esos contenedores y los levanta juntos.
Esta guía está pensada para desarrolladores que ya manejan un servidor Linux (SSH, apt, systemd, permisos). Instalaremos Docker Engine y el plugin de Compose en Ubuntu y Debian desde el repositorio oficial, explicaremos los conceptos que hay que entender de verdad, y desplegaremos un stack con servidor web y base de datos.
Conceptos básicos antes de instalar
Casi todos los problemas con Docker vienen de confundir estos términos.
| Concepto | Qué es | Analogía |
|---|---|---|
| Imagen | Plantilla de solo lectura con el sistema de archivos y la configuración de arranque de una aplicación. Se construye por capas. | Una clase |
| Contenedor | Instancia en ejecución de una imagen: un proceso aislado con su propio sistema de archivos, red y usuarios. | Un objeto |
| Registro (registry) | Servicio donde se publican y descargan imágenes. Docker Hub es el público por defecto. | npm o PyPI, pero de imágenes |
| Volumen | Almacenamiento gestionado por Docker que sobrevive a la vida del contenedor. | Un disco externo |
| Bind mount | Carpeta del host montada dentro del contenedor. | Un acceso directo a tu carpeta |
| Red (network) | Red virtual que conecta contenedores; dentro de ella se resuelven por nombre de servicio. | Una VLAN privada |
| Dockerfile | Receta para construir una imagen. | Un script de build |
| Compose | Archivo YAML que define servicios, redes y volúmenes de una aplicación. | Un manifiesto del stack |
Tres ideas que conviene fijar:
- Un contenedor no es una máquina virtual. Comparte el kernel del host. Arranca en milisegundos y pesa megas, no gigas.
- El sistema de archivos de un contenedor es efímero. Si lo eliminas y lo recreas, lo que escribiste dentro se pierde. Todo dato que importe va en un volumen.
- Las imágenes son inmutables. No se “actualiza” un contenedor en caliente: se construye o descarga una imagen nueva y se recrea el contenedor.
Requisitos
- Ubuntu 22.04, 24.04 o posterior, o Debian 12 (bookworm) o posterior, en arquitectura de 64 bits.
- Un usuario con permisos de
sudo. - Acceso a internet para descargar paquetes e imágenes.
Las versiones soportadas cambian con el tiempo: confirma la lista en la documentación oficial de instalación.
Paso 1. Eliminar paquetes que entran en conflicto
Los paquetes docker.io, docker-compose o podman-docker de los repositorios de la distribución chocan con los oficiales. Si existen, quítalos (no borra tus imágenes ni volúmenes):
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
Si apt responde que no hay nada instalado, está bien.
Paso 2. Añadir el repositorio oficial de Docker
Elige el bloque según tu distribución. Ambos instalan la clave GPG y registran el repositorio.
Ubuntu
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
Debian
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
La diferencia es la URL (ubuntu o debian) y el nombre en clave de la versión. Si usas una derivada de Ubuntu (Linux Mint, por ejemplo), UBUNTU_CODENAME apunta a la base correcta.
Paso 3. Instalar Docker Engine y Compose
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Qué instala cada paquete:
docker-ce: el demonio (dockerd) que gestiona imágenes y contenedores.docker-ce-cli: el comandodocker.containerd.io: el runtime que ejecuta realmente los contenedores.docker-buildx-plugin: construcción de imágenes avanzada (docker buildx).docker-compose-plugin: Compose v2, que se usa comodocker compose(con espacio, no con guion).
En Ubuntu y Debian el servicio arranca y queda habilitado solo. Comprueba:
sudo systemctl status docker --no-pager
docker --version
docker compose version
Paso 4. Usar Docker sin sudo
El socket de Docker pertenece al grupo docker. Añade tu usuario y recarga la sesión:
sudo usermod -aG docker $USER
newgrp docker
Aviso de seguridad. Pertenecer al grupo
dockerequivale a tener acceso root en esa máquina: quien controla el demonio puede montar cualquier carpeta del host en un contenedor. Añade solo a usuarios de confianza y evita hacerlo en servidores compartidos.
Paso 5. Verificar la instalación
docker run --rm hello-world
Docker no encuentra la imagen hello-world en local, la descarga de Docker Hub, crea un contenedor, imprime un mensaje y, gracias a --rm, lo elimina al terminar. Si ves “Hello from Docker!”, todo funciona.
Comandos esenciales
Estos comandos cubren el 90 % del trabajo diario:
docker pull nginx:1.27 # descargar una imagen
docker images # listar imágenes locales
docker run -d --name web -p 8080:80 nginx:1.27 # crear y arrancar un contenedor
docker ps # contenedores en ejecución (-a incluye detenidos)
docker logs -f web # seguir los logs
docker exec -it web sh # abrir una shell dentro del contenedor
docker stop web && docker rm web # detener y eliminar
docker rmi nginx:1.27 # eliminar una imagen
Qué hace cada opción de docker run:
-dejecuta en segundo plano (detached).--name weble da un nombre para no depender del ID aleatorio.-p 8080:80publica el puerto 80 del contenedor en el 8080 del host (host:contenedor).--rmelimina el contenedor al detenerse.
Fija siempre una etiqueta de versión (nginx:1.27) y no uses latest en producción: latest cambia sin avisar y rompe despliegues reproducibles.
Datos persistentes: volúmenes y bind mounts
Como el sistema de archivos del contenedor es efímero, hay dos formas de conservar datos:
| Volumen | Bind mount | |
|---|---|---|
| Gestión | Docker (/var/lib/docker/volumes) |
Tú, una ruta del host |
| Uso típico | Bases de datos, datos de la aplicación | Código en desarrollo, archivos de configuración |
| Portabilidad | Alta; independiente de la estructura del host | Depende de que la ruta exista |
| Permisos | Los gestiona Docker | Los del usuario y archivos del host |
docker volume create pgdata
docker run -d --name db -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=secreto postgres:17
docker rm -f db # eliminas el contenedor...
docker run -d --name db2 -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=secreto postgres:17 # ...y los datos siguen ahí
Para inspeccionar y limpiar:
docker volume ls
docker volume inspect pgdata
docker volume rm pgdata # irreversible: borra los datos
Redes entre contenedores
Docker crea una red virtual por defecto, pero la forma útil de conectar servicios es una red definida por el usuario: los contenedores se encuentran por nombre mediante DNS interno. Compose crea una por proyecto automáticamente, así que el servicio web puede conectarse a la base de datos usando el host db, sin IPs.
Solo publica con -p los puertos que deban ser accesibles desde fuera. Una base de datos casi nunca debe publicarse en internet.
Ejemplo de despliegue: servidor web con PostgreSQL
Vamos a levantar dos servicios: Nginx sirviendo una página estática y PostgreSQL con datos persistentes. Es un patrón mínimo que sirve de plantilla para aplicaciones reales (cambias Nginx por tu API).
Estructura del proyecto
mi-stack/
├── compose.yaml
├── .env
└── html/
└── index.html
mkdir -p mi-stack/html && cd mi-stack
echo '<h1>Hola desde Docker</h1>' > html/index.html
Variables de entorno
Los secretos no se escriben dentro del compose.yaml. Guárdalos en .env, que Compose lee automáticamente, y no lo subas al repositorio.
cat > .env <<'EOF'
POSTGRES_USER=app
POSTGRES_PASSWORD=cambia-esta-clave
POSTGRES_DB=appdb
WEB_PORT=8080
EOF
chmod 600 .env
echo ".env" >> .gitignore
El archivo compose.yaml
services:
web:
image: nginx:1.27-alpine
ports:
- "${WEB_PORT}:80"
volumes:
- ./html:/usr/share/nginx/html:ro
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:17-alpine
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 20s
restart: unless-stopped
volumes:
pgdata:
Qué hace cada pieza:
image: imagen y versión fijadas. Variantealpinepara menor tamaño.ports: publica el puerto del servicio web. La base de datos no publica puertos: soloweby otros servicios de la red del proyecto pueden alcanzarla.volumesenweb: un bind mount de solo lectura (:ro) con el contenido estático.volumesendb: el volumen con nombrepgdata, declarado al final del archivo. Aquí viven los datos.healthcheck: Compose ejecutapg_isreadyperiódicamente para saber si la base está lista. El doble$$evita que Compose sustituya la variable antes de tiempo.depends_onconservice_healthy:webespera a que la base esté sana antes de arrancar. Sin la condición, solo se garantizaría el orden de arranque, no que PostgreSQL ya acepte conexiones.restart: unless-stopped: Docker reinicia el contenedor tras un fallo o un reinicio del servidor, salvo que lo hayas detenido a mano.
Levantar, probar y operar
docker compose config # valida el archivo y muestra las variables resueltas
docker compose up -d # crea red, volumen y contenedores
docker compose ps # estado de los servicios
curl http://localhost:8080 # debería devolver el HTML
docker compose logs -f db # logs de un servicio
Conectarte a la base de datos desde dentro del contenedor:
docker compose exec db psql -U app -d appdb -c '\conninfo'
Comprobar la persistencia, que es la prueba que importa:
docker compose exec db psql -U app -d appdb -c 'CREATE TABLE prueba (id int);'
docker compose down # elimina contenedores y red, conserva el volumen
docker compose up -d
docker compose exec db psql -U app -d appdb -c '\dt' # la tabla sigue ahí
Para detener todo y borrar también los datos:
docker compose down -v # -v elimina los volúmenes: irreversible
Actualizar a una versión nueva
Cambia la etiqueta en compose.yaml y aplica:
docker compose pull
docker compose up -d # recrea solo los servicios cuya imagen cambió
docker image prune -f # limpia imágenes huérfanas
Para versiones mayores de PostgreSQL no basta con cambiar la etiqueta: el formato de datos cambia y debes migrar con pg_dump y restaurar.
Construir tu propia imagen
Cuando tu aplicación tiene código propio, defines una imagen con un Dockerfile. Ejemplo para una API de Node.js:
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 3000
CMD ["node", "server.js"]
El orden importa por las capas: copiar primero package*.json e instalar dependencias permite que Docker reutilice esa capa en caché mientras no cambien las dependencias, aunque cambie el código. Después, en Compose, sustituye image: por build: .:
services:
api:
build: .
ports:
- "3000:3000"
env_file: .env
Añade un .dockerignore con node_modules, .git y .env para que no entren en la imagen ni inflen el contexto de build.
Buenas prácticas de seguridad y operación
-
Fija versiones de las imágenes y actualízalas de forma deliberada.
-
No ejecutes como root dentro del contenedor cuando la imagen lo permita (
USER). -
No guardes secretos en la imagen ni en el repositorio. Usa
.envcon permisos restringidos, secretos de Compose o el gestor de secretos de tu plataforma. -
Publica el mínimo de puertos. Si el servidor está expuesto a internet, recuerda que Docker modifica
iptablesy puede saltarse reglas deufwpara los puertos publicados: enlaza a127.0.0.1("127.0.0.1:5432:5432") cuando solo necesites acceso local. -
Limita los logs para que no llenen el disco. En
/etc/docker/daemon.json:{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" } }Aplica con
sudo systemctl restart docker. Afecta solo a los contenedores nuevos. -
Haz copia de seguridad de los volúmenes, no solo del código. Para PostgreSQL, usa
pg_dump:docker compose exec -T db pg_dump -U app appdb > backup.sql -
Limpia con criterio.
docker system dfmuestra qué ocupa espacio.docker system pruneelimina contenedores detenidos, redes y capas sin uso;docker system prune --volumestambién borra volúmenes huérfanos, así que revisa antes.
Problemas comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
permission denied ... /var/run/docker.sock |
Tu usuario no está en el grupo docker |
Paso 4 y reabrir sesión |
docker: 'compose' is not a docker command |
Falta el plugin o usas la guía de Compose v1 | sudo apt install docker-compose-plugin; usa docker compose, no docker-compose |
port is already allocated |
Otro proceso usa ese puerto del host | Cambia WEB_PORT o detén el otro proceso (ss -ltnp) |
La base arranca vacía tras up |
El volumen cambió de nombre o hiciste down -v |
Revisa docker volume ls; el prefijo del volumen es el nombre del proyecto |
| Un servicio no resuelve a otro por nombre | No comparten red | Déjalos en el mismo compose.yaml o define una red común |
no matching manifest for linux/arm64 |
La imagen no publica tu arquitectura | Busca otra etiqueta o usa --platform |
Para diagnosticar, empieza siempre por docker compose ps, luego docker compose logs <servicio> y, si hace falta, docker inspect <contenedor>.
Resumen de comandos
# Instalación (Ubuntu o Debian, tras añadir el repositorio)
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
# Ciclo diario con Compose
docker compose up -d
docker compose ps
docker compose logs -f <servicio>
docker compose exec <servicio> sh
docker compose pull && docker compose up -d
docker compose down
Preguntas frecuentes
¿Cuál es la diferencia entre una imagen y un contenedor?
La imagen es la plantilla inmutable; el contenedor es una instancia en ejecución creada a partir de ella. Puedes crear muchos contenedores desde una misma imagen, y borrar un contenedor no elimina la imagen.
¿Cuál es la diferencia entre docker-compose y docker compose?
docker-compose (con guion) es la versión 1, escrita en Python y sin soporte desde 2023. docker compose es la versión 2, integrada como plugin de Docker. Usa siempre la segunda.
¿Debo instalar Docker desde apt install docker.io?
Funciona, pero suele traer versiones más antiguas que el repositorio oficial de Docker. Para servidores donde necesitas actualizaciones de seguridad y funciones recientes, el repositorio oficial es la opción recomendada.
¿Cuándo uso un volumen y cuándo un bind mount?
Usa volúmenes para datos que la aplicación genera y debes conservar (bases de datos, subidas). Usa bind mounts para archivos que editas tú en el host: código durante el desarrollo o archivos de configuración.
¿Docker Compose sirve para producción?
Sí, para un único servidor o servicios de tamaño moderado. Cuando necesitas varios nodos, escalado automático o despliegues sin caída entre máquinas, el siguiente paso es un orquestador como Kubernetes o Docker Swarm.
Para seguir leyendo
- Docker, Instalar Docker Engine en Ubuntu
- Docker, Instalar Docker Engine en Debian
- Docker, Referencia del archivo Compose
- Docker, Pasos posteriores a la instalación en Linux

