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.

Diagrama de Docker Compose: servicios web, api y db conectados por una red y un volumen

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:

  1. Un contenedor no es una máquina virtual. Comparte el kernel del host. Arranca en milisegundos y pesa megas, no gigas.
  2. 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.
  3. 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 comando docker.
  • 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 como docker 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 docker equivale 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:

  • -d ejecuta en segundo plano (detached).
  • --name web le da un nombre para no depender del ID aleatorio.
  • -p 8080:80 publica el puerto 80 del contenedor en el 8080 del host (host:contenedor).
  • --rm elimina 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. Variante alpine para menor tamaño.
  • ports: publica el puerto del servicio web. La base de datos no publica puertos: solo web y otros servicios de la red del proyecto pueden alcanzarla.
  • volumes en web: un bind mount de solo lectura (:ro) con el contenido estático.
  • volumes en db: el volumen con nombre pgdata, declarado al final del archivo. Aquí viven los datos.
  • healthcheck: Compose ejecuta pg_isready periódicamente para saber si la base está lista. El doble $$ evita que Compose sustituya la variable antes de tiempo.
  • depends_on con service_healthy: web espera 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 .env con 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 iptables y puede saltarse reglas de ufw para los puertos publicados: enlaza a 127.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 df muestra qué ocupa espacio. docker system prune elimina contenedores detenidos, redes y capas sin uso; docker system prune --volumes tambié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

Sobre el autor

Rootnite Engineering

Equipo de ingeniería de Rootnite

Los ingenieros detrás del software a medida, la automatización y los productos de Rootnite. Documentamos las prácticas que usamos para construir y operar sistemas en producción para que otros equipos puedan reutilizarlas.

  • Docker
  • Docker Compose
  • Ubuntu
  • Debian
  • DevOps
  • Contenedores

¿Necesitas un equipo que trabaje así?

Diseñamos, construimos y operamos software de producción con las prácticas de estas guías. Cuéntanos sobre tu proyecto.

Contactar a Rootnite