DOCKER
Guía de Referencia
Conceptos, configuración y comandos esenciales
1. ¿Qué es Docker?
Docker es una plataforma de contenedorización que permite empaquetar una aplicación
junto con todas sus dependencias, librerías y configuraciones en una unidad estándar
denominada contenedor. El objetivo principal es garantizar que el software se ejecute de
forma idéntica en cualquier entorno, ya sea en la máquina de un desarrollador, en un
servidor de pruebas o en producción.
La idea central es eliminar el clásico problema de "en mi máquina funciona": al encapsular
todo lo necesario dentro del contenedor, la aplicación se comporta siempre igual
independientemente del sistema operativo o configuración del host.
2. Conceptos Fundamentales
2.1 Contenedor
Un contenedor es una instancia en ejecución de una imagen Docker. Se puede pensar en él
como un proceso aislado que tiene su propio sistema de archivos, red y espacio de
procesos, pero comparte el kernel del sistema operativo host. Los contenedores son:
• Ligeros: no incluyen un sistema operativo completo como las máquinas virtuales.
• Portables: se ejecutan igual en cualquier host que tenga Docker instalado.
• Efímeros: pueden levantarse, detenerse y destruirse rápidamente.
• Aislados: cada contenedor opera de forma independiente.
2.2 Imagen
Una imagen es una plantilla de solo lectura a partir de la cual se crean los contenedores.
Contiene el código de la aplicación, el entorno de ejecución, las librerías y todas las
configuraciones necesarias. Las imágenes se construyen a partir de un archivo llamado
Dockerfile y pueden almacenarse en registros como Docker Hub.
La imagen es como un "molde" y el contenedor es el objeto fabricado con ese
Analogía
molde. A partir de una misma imagen se pueden lanzar múltiples contenedores.
2.3 Volumen
Un volumen es el mecanismo de Docker para persistir datos generados o utilizados por los
contenedores. Dado que los contenedores son efímeros (sus datos internos se pierden al
ser destruidos), los volúmenes permiten que la información sobreviva al ciclo de vida del
contenedor.
• Los volúmenes son gestionados por Docker y se almacenan fuera del sistema de
archivos del contenedor.
• Son ideales para bases de datos, archivos de configuración y cualquier dato que
deba persistir.
• Se definen en el [Link] tanto a nivel de servicio (montaje) como a
nivel global (declaración).
2.4 Red (Network)
Docker crea redes virtuales que permiten la comunicación entre contenedores. Cuando se
define una red en [Link], todos los servicios que la usen pueden comunicarse
entre sí utilizando el nombre del servicio como hostname.
• Permite aislar la comunicación interna de la red pública.
• Un servicio de backend puede conectarse a la base de datos usando simplemente el
nombre del servicio (ej. postgres o db).
• Se pueden definir múltiples redes para separar grupos de servicios.
3. Mapeo de Puertos
El mapeo de puertos es el mecanismo por el cual un puerto del contenedor se expone en un
puerto de la máquina host. La sintaxis en [Link] es:
ports:
- "3010:3000" # host_port:container_port
En el ejemplo anterior, la aplicación escucha en el puerto 3000 dentro del contenedor, pero
desde el exterior se accede a través del puerto 3010 del host. Esto permite:
• Evitar conflictos de puertos cuando hay múltiples servicios corriendo en el mismo
host.
• Controlar qué servicios son accesibles desde el exterior y cuáles solo internamente.
• Exponer únicamente los puertos necesarios por razones de seguridad.
Si un servicio solo necesita comunicarse con otros contenedores, no es
Nota necesario exponer ningún puerto al host. La comunicación interna se realiza a
través de la red de Docker.
4. Docker Compose
Docker Compose es una herramienta que permite definir y gestionar aplicaciones multi-
contenedor mediante un archivo de configuración en formato YAML denominado docker-
[Link]. Con un solo archivo se puede describir toda la arquitectura de la aplicación:
sus servicios, redes, volúmenes y dependencias.
4.1 Estructura del archivo [Link]
version: '3.9'
services:
api: # Nombre del servicio
build: ./api # Ruta al Dockerfile
container_name: mi_api # Nombre del contenedor
ports:
- "3010:3000" # host:contenedor
volumes:
- ./api:/app # Montaje del código fuente
environment:
- NODE_ENV=production
- DB_HOST=db
depends_on:
- db # Espera a que db esté listo
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
networks:
- app_network
db:
image: postgres:15 # Imagen oficial de PostgreSQL
container_name: mi_db
environment:
POSTGRES_DB: mi_base
POSTGRES_USER: usuario
POSTGRES_PASSWORD: clave
volumes:
- db_data:/var/lib/postgresql/data
networks:
- app_network
volumes:
db_data: # Volumen persistente para la BD
networks:
app_network: # Red compartida entre servicios
4.2 Propiedades principales de un servicio
image / build
Define el origen del contenedor. Se puede usar una imagen pública (image: postgres:15) o
construir una propia a partir de un Dockerfile (build: ./ruta).
container_name
Asigna un nombre personalizado al contenedor. Si no se especifica, Docker genera uno
automáticamente.
Ports,
Mapea puertos entre el host y el contenedor en formato "host:contenedor". Solo se deben
exponer los puertos necesarios para el acceso externo.
volumes
Define los montajes de datos. Pueden ser montajes de código fuente (bind mounts) para
desarrollo, o volúmenes nombrados para persistencia de datos de producción (bases de
datos, archivos generados).
environment
Variables de entorno inyectadas en el contenedor. Son fundamentales para configurar
credenciales, rutas, modos de ejecución y cualquier parámetro que varíe entre entornos.
depends_on
Define dependencias de orden de inicio entre servicios. Por ejemplo, si el servicio api
depende de db, Docker Compose intentará iniciar db antes que api. Esto evita saturar los
recursos del host al levantar todos los contenedores simultáneamente y previene errores de
conexión por inicio prematuro.
depends_on solo garantiza el orden de inicio, no que el servicio dependiente
Important
esté completamente listo. Para esperar a que una base de datos esté
e
operativa, se recomienda usar herramientas como wait-for-it o healthchecks.
[Link]
Permite limitar los recursos de CPU y memoria que puede consumir un contenedor. Esto es
especialmente útil en servidores con recursos limitados para evitar que un servicio
monopolice el hardware.
deploy:
resources:
limits:
cpus: '0.50' # Máximo 50% de un núcleo
memory: 512M # Máximo 512 MB de RAM
networks
Especifica las redes a las que pertenece el servicio. Los servicios en la misma red pueden
comunicarse entre sí usando el nombre del servicio como dirección.
5. Imágenes y Proceso de Build
5.1 ¿Qué es una imagen Docker?
Cuando se ejecuta docker compose up, Docker construye (o recupera del caché) una
imagen para cada servicio que define un Dockerfile. Esta imagen es una "fotografía" del
estado del código y la configuración en el momento del build. Docker almacena estas
imágenes localmente para acelerar futuros inicios.
5.2 El problema del caché de imágenes
Si se realizan cambios en el código fuente o en el Dockerfile y luego se ejecuta docker
compose up -d, Docker reutilizará la imagen en caché sin reflejar los cambios. Esto se debe
a que Docker prioriza la velocidad reutilizando capas de imagen ya construidas.
Problema Modifico mi código, bajo el contenedor, lo vuelvo a levantar y... los cambios no
común aparecen. Esto sucede porque Docker usa la imagen cacheada.
5.3 Solución: forzar el rebuild
Para que Docker reconstruya las imágenes y refleje los cambios, se debe usar el flag --
build:
docker compose up -d --build
Este comando instruye a Docker a reconstruir todas las imágenes antes de iniciar los
contenedores, asegurando que cualquier cambio en el Dockerfile o en el contexto de build
quede incorporado.
6. Comandos Esenciales
Comando Descripción
docker compose up -d Levanta todos los servicios en segundo plano (detached
mode).
docker compose up -d -- Reconstruye las imágenes y levanta los servicios.
build Necesario al cambiar el código.
docker compose down Detiene y elimina los contenedores. Conserva los
volúmenes por defecto.
docker compose down -v Detiene, elimina contenedores Y también elimina los
volúmenes. Útil para limpiar datos.
docker compose stop Detiene los contenedores sin eliminarlos. Se pueden
volver a iniciar con start.
docker compose start Inicia contenedores previamente detenidos con stop.
docker compose restart Reinicia todos los servicios.
docker compose logs -f Muestra los logs en tiempo real de todos los servicios.
docker compose logs -f api Muestra los logs en tiempo real de un servicio
específico.
docker compose ps Lista los contenedores activos del proyecto.
docker compose exec api sh Abre una shell interactiva dentro del contenedor 'api'.
docker images Lista todas las imágenes almacenadas localmente.
docker rmi <image_id> Elimina una imagen local por su ID.
docker system prune Limpia imágenes, contenedores y redes no utilizados.
7. Configuración Específica por Tipo de Servicio
7.1 Base de datos (PostgreSQL)
db:
image: postgres:15
environment:
POSTGRES_DB: nombre_base
POSTGRES_USER: usuario
POSTGRES_PASSWORD: contrasena_segura
volumes:
- db_data:/var/lib/postgresql/data
ports:
- "5432:5432" # Solo si se necesita acceso externo
Las variables de entorno POSTGRES_DB, POSTGRES_USER y
POSTGRES_PASSWORD son requeridas por la imagen oficial de PostgreSQL para
inicializar la base de datos. El volumen garantiza que los datos persistan aunque el
contenedor se elimine.
7.2 Aplicación [Link] / NestJS
api:
build:
context: ./api
dockerfile: Dockerfile
ports:
- "3010:3000"
environment:
- NODE_ENV=production
- DATABASE_URL=postgresql://usuario:clave@db:5432/nombre_base
depends_on:
- db
volumes:
- ./api:/app # Para desarrollo con hot-reload
- /app/node_modules # Excluye node_modules del bind mount
7.3 Servidor web (Nginx)
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/[Link]:/etc/nginx/[Link]:ro
- ./frontend/dist:/usr/share/nginx/html:ro
depends_on:
- api
8. Buenas Prácticas
8.1 Seguridad
• Nunca incluir credenciales directamente en el [Link]. Usar
archivos .env y referenciarlos con ${VARIABLE}.
• Agregar el archivo .env al .gitignore para no subir credenciales al repositorio.
• Exponer solo los puertos estrictamente necesarios al exterior.
• Usar imágenes oficiales de fuentes confiables (Docker Hub Official Images).
8.2 Rendimiento y recursos
• Definir límites de recursos (CPU y memoria) para cada servicio en entornos de
producción.
• Usar depends_on para controlar el orden de inicio y no saturar el host.
• Aprovechar el caché de capas de Docker ordenando el Dockerfile de menos a más
cambiante.
• En producción, no montar el código fuente como volumen; incluirlo directamente en
la imagen.
8.3 Volúmenes y datos
• Usar volúmenes nombrados (no bind mounts) para datos de bases de datos en
producción.
• Usar docker compose down -v con precaución, ya que elimina permanentemente los
datos de los volúmenes.
• Implementar backups regulares de los volúmenes de bases de datos.
8.4 Desarrollo vs Producción
• Mantener archivos separados: [Link] para producción y docker-
[Link] para desarrollo.
• En desarrollo, usar bind mounts del código fuente para ver cambios sin rebuild.
• En producción, copiar el código dentro de la imagen en el Dockerfile.
9. Flujo de Trabajo Típico
Paso 1 Crear el Dockerfile para cada servicio que requiere una imagen personalizada.
Definir todos los servicios, redes y volúmenes en el archivo docker-
Paso 2
[Link].
Paso 3 Crear el archivo .env con las variables sensibles (credenciales, configuraciones).
Ejecutar docker compose up -d --build para construir las imágenes e iniciar los
Paso 4
contenedores.
Verificar el estado con docker compose ps y revisar logs con docker compose
Paso 5
logs -f.
Paso 6 Al modificar código: docker compose up -d --build para reconstruir las imágenes.
Para detener todo: docker compose down. Para detener y limpiar datos: docker
Paso 7
compose down -v.
10. Glosario Rápido
Comando Descripción
Contenedor Instancia en ejecución de una imagen. Proceso aislado
con su propio entorno.
Imagen Plantilla inmutable a partir de la cual se crean los
contenedores.
Dockerfile Archivo de instrucciones para construir una imagen
personalizada.
[Link] Archivo de configuración que define servicios, redes y
volúmenes.
Volumen Mecanismo para persistir datos fuera del ciclo de vida
del contenedor.
Network Red virtual que permite la comunicación entre
contenedores.
Bind mount Montaje de un directorio del host dentro del contenedor.
Usado en desarrollo.
depends_on Define el orden de inicio entre servicios.
Build context Directorio cuyo contenido se envía al daemon de
Docker al construir una imagen.
Registry Repositorio de imágenes Docker (ej. Docker Hub,
GitHub Container Registry).