Docker - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

Docker

1. Propósito

Esta página documenta la configuración y el uso de Docker en BuenOrigen Backend, incluyendo la construcción de imágenes, la ejecución de contenedores y las comprobaciones realizadas para verificar que la aplicación se inicia correctamente.

Docker permite empaquetar la aplicación y sus dependencias de ejecución en una imagen, facilitando su ejecución en diferentes entornos.

La configuración de la infraestructura y el procedimiento completo de publicación en Oracle Cloud se documentan en Despliegue.

2. Archivos de configuración

La configuración Docker incorpora los siguientes archivos en la raíz del repositorio:

Archivo Propósito
Dockerfile Define la construcción de la imagen y la configuración de ejecución de la aplicación.
.dockerignore Excluye archivos y directorios innecesarios o sensibles del contexto de construcción.

2.1. Dockerfile

El Dockerfile utiliza una construcción multietapa (multi-stage build) basada en node:22-alpine.

La etapa de construcción:

  1. Define el directorio de trabajo /app.
  2. Copia los archivos de dependencias.
  3. Instala las dependencias mediante npm ci.
  4. Copia el código fuente.
  5. Compila la aplicación mediante npm run build.

La etapa de producción:

  1. Utiliza una nueva imagen node:22-alpine.
  2. Define NODE_ENV=production.
  3. Instala únicamente las dependencias de producción mediante npm ci --omit=dev.
  4. Copia el directorio compilado dist desde la etapa de construcción.
  5. Expone el puerto 3000.
  6. Inicia la aplicación con node dist/main.js.

Esta separación evita incluir el código fuente completo y las dependencias de desarrollo en la etapa final de producción.

2.2. .dockerignore

El archivo .dockerignore excluye del contexto de construcción, entre otros elementos:

  • node_modules
  • dist
  • .git
  • .env
  • Archivos .env.*
  • Directorios coverage
  • Archivos de registro *.log

También permite explícitamente .env.example.

La exclusión de archivos de entorno reduce el riesgo de incorporar configuraciones locales o secretos a la imagen. No sustituye la revisión del código ni garantiza por sí sola que no existan credenciales en otros archivos.

3. Construcción de la imagen

La imagen de QA se construyó correctamente desde la rama qa.

Desde la raíz del repositorio, ejecutar:

docker build -t buenorigen-backend:qa .

El comando utiliza el Dockerfile del directorio actual y genera la imagen buenorigen-backend:qa.

Resultado verificado: la construcción finalizó correctamente tanto en el equipo local como en la VM de Oracle Cloud.

Para comprobar las imágenes disponibles localmente:

docker images

4. Ejecución del contenedor

La imagen de QA se ejecutó en un contenedor independiente, publicando el puerto 3000 del contenedor en el puerto 3003 del host.

docker run -d --name buenorigen-qa -p 3003:3000 buenorigen-backend:qa

Significado de los parámetros:

Parámetro Descripción
-d Ejecuta el contenedor en segundo plano.
--name buenorigen-qa Asigna un nombre al contenedor.
-p 3003:3000 Publica el puerto 3000 del contenedor en el puerto 3003 del host.
buenorigen-backend:qa Identifica la imagen utilizada.

El puerto del host puede variar según el entorno y los puertos disponibles. En la VM utilizada para las pruebas, 3003 se reservó para el contenedor de QA.

5. Verificación del contenedor

Para comprobar que el contenedor está en ejecución:

docker ps --filter "name=buenorigen-qa"

Para consultar también los contenedores detenidos:

docker ps -a

Para revisar los registros de ejecución:

docker logs buenorigen-qa

Resultado verificado: el contenedor buenorigen-qa apareció en estado Up y mostró el mapeo de puertos 3003:3000.

6. Verificación de Swagger

Se verificó que la aplicación servía la página de Swagger desde el contenedor.

Desde la propia VM se ejecutó:

curl -i http://localhost:3003/api

La respuesta obtenida fue:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

También se comprobó el acceso a Swagger desde un navegador mediante el puerto publicado de la VM. La configuración de acceso externo se describe en Despliegue.

Alcance de la prueba: esta verificación confirma que la página de Swagger responde. No demuestra por sí sola que todos los endpoints, validaciones y operaciones de negocio funcionen correctamente.

7. Variables de entorno

El archivo .dockerignore excluye los archivos .env y .env.*, y permite .env.example.

Antes de considerar completa la configuración, se debe verificar cuáles son las variables realmente requeridas por BuenOrigen Backend y cómo se proporcionan al contenedor.

Las variables documentadas deben incluir su nombre, propósito y si son obligatorias, sin publicar valores secretos.

No se enumeran variables específicas en esta página porque deben confirmarse contra la configuración efectiva de la aplicación.

8. Buenas prácticas de seguridad

  • No incorporar credenciales, claves privadas ni secretos a la imagen.
  • Mantener excluidos del contexto de construcción los archivos locales que no sean necesarios.
  • Evitar publicar puertos innecesarios.
  • Verificar los controles de autenticación y autorización antes de exponer la API públicamente.
  • Revisar los logs cuando el contenedor no inicia o la aplicación presenta errores.
  • Mantener separadas las imágenes y los contenedores de prueba del servicio estable.

9. Estado de las pruebas

Comprobación Resultado
Construcción de la imagen buenorigen-backend:qa Correcta
Inicio del contenedor buenorigen-qa Correcto
Publicación del puerto 3003:3000 Verificada
Respuesta HTTP de Swagger desde la VM 200 OK
Acceso externo a Swagger Verificado tras configurar el acceso de red
Pruebas completas de endpoints y reglas de negocio Pendientes de completar

10. Referencias