3.4.-Requisitos de implantación

3.4. Requisitos de implantación

Idea principal

El análisis de la aplicación dice qué componentes tiene; la ficha de requisitos describe qué debe ofrecer el entorno para que esos componentes puedan ejecutarse de forma segura, verificable y reproducible.

Un despliegue puede fallar sin que exista un error en el código. Basta con que falte una versión compatible, un puerto libre, un volumen, una variable de entorno, un permiso de escritura o una regla de red. Este apunte enseña a detectar esas condiciones antes de instalar y a dejar una evidencia de cada comprobación.

El objetivo de este tema no es memorizar una lista de comandos, sino aprender a traducir la documentación de una aplicación en condiciones técnicas que se puedan comprobar antes, durante y después del despliegue.

Este punto se relaciona con el punto anterior, pero no es lo mismo:

• en 3.3. Estructura de una aplicación web se identifican la estructura y los recursos que componen la aplicación;
• en 3.4. Requisitos de implantación se describe qué necesita el entorno para poder implantarla y cómo se demostrará que está preparado.

La asociación curricular es exclusivamente la siguiente:

Código	Descripción
RA1	Implanta arquitecturas web analizando y aplicando criterios de funcionalidad.
CE h	Se han descrito los requerimientos del proceso de implantación de una aplicación web.

Qué deberías saber al terminar

Deberías poder:

• extraer requisitos de la documentación, del artefacto y del entorno de ejecución;
• clasificar requisitos de sistema, software, red, configuración, persistencia, seguridad y operación;
• expresar cada requisito con un valor esperado y una evidencia;
• entregar una ficha previa al despliegue, con responsables y excepciones registradas.

Mapa del tema

Partiremos de las fuentes de información, clasificaremos y priorizaremos los requisitos, estudiaremos una arquitectura concreta y cerraremos con una ficha de comprobación aplicada a un caso web con base de datos.

1. Leer y contrastar la documentación de despliegue

La documentación de una aplicación puede estar en README.md, en el artefacto generado, en la imagen del contenedor, en compose.yaml, en el sistema de construcción o en una guía específica del proveedor. No todas las fuentes están igual de actualizadas ni tienen la misma relación con la versión que vamos a instalar.

Por ejemplo, una guía antigua puede explicar cómo ejecutar el proyecto con Java 11, mientras que el pom.xml actual exige Java 17. En ese caso no debemos copiar la guía sin comprobarla: hay que contrastar la versión del artefacto, el fichero de dependencias y el entorno real.

Fuente	Qué podemos confirmar	Riesgo que hay que revisar
README.md y guía de instalación	Comandos, orden de arranque y comprobaciones	Puede estar desactualizada
Artefacto o imagen versionada	Qué se va a instalar y qué runtime espera	La etiqueta puede ser mutable
pom.xml, package.json o requirements.txt	Dependencias y versiones declaradas	No garantiza que el host las soporte
Dockerfile y compose.yaml	Servicios, puertos, variables, redes y volúmenes	Puede contener valores inseguros o de desarrollo
Documentación del proveedor	Compatibilidad, límites y configuración oficial	Puede referirse a otra edición
Inventario del servidor	Recursos, puertos y software realmente disponibles	Es una fotografía que debe fecharse

Antes de ejecutar comandos con privilegios, registra como mínimo:

• versión de la aplicación, del artefacto y de sus imágenes;
• sistema operativo, arquitectura y recursos de la máquina anfitriona;
• runtime, servidor y dependencias compatibles;
• servicios externos, nombres de red y puertos necesarios;
• comandos de instalación, inicio, parada, comprobación y recuperación;
• variables de configuración, tipo, obligatoriedad y valores permitidos;
• fecha, origen de cada dato y persona responsable de validarlo.

Una fuente no sustituye a una comprobación

Un README explica la intención del proyecto, pero no demuestra que el puerto esté libre ni que la versión instalada sea compatible. La ficha debe conservar tanto el dato esperado como la evidencia obtenida en el entorno.

2. Clasificar y priorizar los requisitos

Un requisito de implantación es una condición que el entorno debe cumplir para instalar, iniciar, conectar, proteger, comprobar o recuperar una aplicación. Debe poder comprobarse y debe indicar qué ocurre si no se cumple.

Definición

Un requisito de implantación describe una condición necesaria del entorno, junto con el valor esperado y la prueba que permitirá aceptar o rechazar esa condición.

Conviene distinguir tres ideas que suelen mezclarse:

Concepto	Significado	Ejemplo
Requisito	Condición necesaria para implantar	El servicio necesita Java 17
Restricción	Límite que condiciona la solución	Solo se puede publicar el puerto 443
Supuesto	Dato provisional que aún debe confirmarse	La base de datos estará en la misma red

Una forma útil de clasificar los requisitos es la siguiente:

Categoría	Preguntas	Ejemplo verificable
Sistema	¿Qué sistema, arquitectura y recursos hacen falta?	Linux amd64, 2 vCPU y 4 GiB de RAM
Software	¿Qué runtime, servidor, biblioteca o plugin se necesita?	Java 17 y Tomcat 10 compatibles
Red	¿Qué puertos, DNS y conexiones se permiten?	443 público; 3306 solo interno
Configuración	¿Qué variables, rutas y modos necesita?	DB_HOST, APP_ENV y PORT definidos
Almacenamiento	¿Qué datos persisten y cuánto ocupan?	Volumen de 10 GiB para la base de datos
Seguridad	¿Qué permisos, certificados y secretos exige?	TLS y usuario de servicio sin privilegios
Operación	¿Cómo se inicia, verifica, actualiza y recupera?	Healthcheck y restauración probada
Coste y límites	¿Qué consumo, cuotas o restricciones existen?	Instancia cloud dentro del presupuesto

No todos los requisitos tienen la misma prioridad. Marca al menos si son obligatorios, recomendados o pendientes de decisión. Un requisito obligatorio incumplido bloquea la instalación; uno recomendado puede convertirse en una mejora planificada, pero no debe desaparecer de la ficha.

Un requisito útil debe ser concreto. «El servidor debe ser rápido» no define una prueba; «la ruta /health debe devolver 200 en menos de 500 ms desde la red interna, en las condiciones indicadas» sí permite planificarla. Si el valor no se conoce todavía, se escribe pendiente y se asigna una persona para confirmarlo: no se inventa.

3. Dependencias, puertos y configuración

La aplicación de referencia puede necesitar un servidor web, un proceso de aplicación y una base de datos. El navegador no debería conocer directamente la base de datos: cada servicio tiene una responsabilidad y una red de acceso.

flowchart LR
  C["Cliente"] -->|HTTPS 443| W["Servidor web"]
  W -->|HTTP interno 8080| A["Aplicacion"]
  A -->|TCP interno 3306| D["Base de datos"]
  A --> V["Volumen persistente"]

3.1. Puertos y redes

La ficha debe distinguir entre puerto del servicio, puerto publicado y puerto permitido por el firewall:

• el puerto del servicio es donde escucha el proceso dentro de su entorno;
• el puerto publicado conecta el host con el contenedor o servidor;
• el firewall decide desde qué orígenes se acepta la conexión.

Que MariaDB escuche en 3306 dentro de una red no implica que deba publicarse en 3306 del host. En una aplicación sencilla suele bastar con publicar el servidor web y mantener la base de datos en una red interna. Publicar solo los puntos de entrada necesarios reduce la superficie de exposición.

En Docker Compose, ports publica un puerto hacia el host y expose documenta un puerto para la comunicación interna entre servicios. El nombre del servicio, como db, funciona como nombre DNS dentro de la red de Compose; no conviene fijar una dirección IP que pueda cambiar al recrear el contenedor.

expose no sustituye a una política de seguridad: la separación real depende de las redes, del firewall y de los permisos del servicio. Del mismo modo, depends_on puede ordenar el arranque, pero no garantiza que la base de datos ya acepte conexiones. La aplicación debe reintentar la conexión o utilizar un healthcheck que represente la disponibilidad real del servicio.

3.2. Versiones y compatibilidad

La compatibilidad no se reduce a «tener instalada la última versión». Hay que relacionar las versiones que trabajan juntas:

Componente	Versión probada	Dependencia o límite que se debe confirmar
Aplicación	1.4.2	Artefacto que se va a desplegar
Runtime	Java 17	Requisito declarado por el artefacto
Servidor web	Nginx 1.27	Configuración de proxy y TLS
Base de datos	MariaDB 11	Esquema y controlador compatibles
Motor de contenedores	Docker Engine 26	Compose y arquitectura del host

Las etiquetas como latest pueden cambiar. Para una práctica o una entrega reproducible se registra la versión y, cuando sea necesario, el digest de la imagen. Si se decide actualizar, se anota la nueva prueba en lugar de cambiarla silenciosamente.

3.3. Variables, archivos y secretos

Las variables de entorno permiten separar el mismo artefacto de los valores de cada entorno. La ficha documentará, para cada variable, su nombre, tipo, obligatoriedad, valor de ejemplo y procedencia.

# .env.example: solo nombres y valores de ejemplo, nunca secretos reales
WEB_PORT=8080
DB_HOST=db
DB_NAME=catalogo
DB_USER=catalogo_app
DB_PASSWORD=rellenar-fuera-del-repositorio

services:
  app:
    image: catalogo-web:1.4.2
    environment:
      DB_HOST: ${DB_HOST}
      DB_NAME: ${DB_NAME}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
    expose:
      - "8080"
    networks:
      - frontend
      - backend

  db:
    image: mariadb:11
    volumes:
      - datos-db:/var/lib/mysql
    networks:
      - backend

networks:
  frontend:
  backend:

volumes:
  datos-db:

Este fragmento es una ilustración de los requisitos, no una configuración completa lista para producción. La imagen catalogo-web:1.4.2 debe existir y la imagen de la base de datos necesita las variables de inicialización que indique su documentación. Las contraseñas reales se suministran mediante un gestor de secretos o una configuración protegida, nunca se escriben en el repositorio ni en el documento.

4. Ficha de requisitos previos

La ficha convierte una explicación general en una lista auditable. Cada fila debe responder a cinco preguntas: qué se necesita, cuánto se espera, cómo se comprueba, quién lo valida y qué estado tiene.

Un requisito solo resulta útil cuando se relaciona con una evidencia y con una decisión sobre el despliegue.

Una ficha ampliada para el caso de ejemplo podría ser:

ID	Requisito y prioridad	Valor esperado	Evidencia	Responsable	Estado
R-01	Host y arquitectura, obligatorio	Linux amd64, 2 vCPU, 4 GiB RAM	uname, lscpu, free -h	Infraestructura	Pendiente
R-02	Versiones, obligatorio	App 1.4.2, Java 17, MariaDB 11	Release, manifest y comandos de versión	Desarrollo	Pendiente
R-03	Entrada web, obligatorio	443 permitido; 8080 solo local en pruebas	Firewall, ss y prueba HTTPS	Infraestructura	Pendiente
R-04	Red interna, obligatorio	La aplicación resuelve db:3306	Configuración y prueba desde la red	Desarrollo	Pendiente
R-05	Persistencia, obligatorio	Datos y cargas sobreviven al recrear servicios	Inspección y restauración de prueba	Operación	Pendiente
R-06	Secretos, obligatorio	No hay credenciales en Git ni en logs	Revisión de repositorio y configuración	Seguridad	Pendiente
R-07	Salud, recomendado	/health devuelve 200	curl y resultado del healthcheck	Desarrollo	Pendiente
R-08	Recuperación, obligatorio	Copia y restauración documentadas	Registro de una restauración	Operación	Pendiente

Los estados deben tener un significado acordado. Por ejemplo, Conforme significa que existe evidencia; Bloqueado, que impide continuar; y Excepción, que se acepta una desviación con responsable y fecha de revisión. Pendiente no significa «correcto»: significa que todavía falta comprobarlo.

Diferencia con 3.3. Estructura de una aplicación web

En 3.3. Estructura de una aplicación web identificamos que la aplicación usa una base de datos y un directorio de cargas. En 3.4. Requisitos de implantación convertimos esa observación en requisitos: una base de datos compatible, una red que permita la conexión, un volumen con permisos y copias de seguridad, y una prueba que demuestre cada punto.

5. Aplicación al caso antes de instalar

Supongamos una aplicación de catálogo con esta arquitectura: el navegador entra por el servidor web, el servidor web reenvía al proceso de aplicación en el puerto interno 8080 y la aplicación consulta MariaDB en 3306. Las imágenes, los registros y los datos de la base de datos no tienen todos el mismo ciclo de vida, por lo que se documentan por separado.

La ficha se revisa con la persona responsable de desarrollo y con quien administre la infraestructura. El siguiente procedimiento evita empezar por docker compose up sin saber qué se está comprobando.

1. Fijar el alcance y las versiones: identifica el artefacto, las imágenes, la arquitectura del host y el entorno objetivo. Guarda la referencia de cada versión y marca como pendiente cualquier dato que aún no esté confirmado.

2. Comprobar el anfitrión: revisa sistema, arquitectura, memoria, disco, motor de contenedores y puertos sin modificar todavía la configuración.

   uname -a
   uname -m
   free -h
   df -h
   docker version
   ss -ltn
   

   La evidencia debe incluir la fecha y el nombre de la máquina. Si el puerto previsto ya está ocupado, se resuelve la colisión o se actualiza la ficha; no se detiene otro servicio sin autorización.

3. Validar la configuración declarativa: prepara un .env protegido a partir de .env.example y revisa la configuración expandida antes de crear servicios.

   docker compose config
   docker compose config --quiet
   

   config permite detectar errores de YAML, variables ausentes y valores inesperados. Su salida no debe copiarse a un informe si contiene secretos.

4. Instalar y comprobar el arranque: inicia el entorno solo cuando los requisitos bloqueantes estén conformes y conserva la salida relevante.

   docker compose up --detach
   docker compose ps
   docker compose logs --tail 50
   curl --fail --silent --show-error http://localhost:8080/health
   

   Una respuesta HTTP correcta no demuestra por sí sola que la base de datos esté bien protegida ni que los datos sean recuperables. Hay que contrastar también la red, los volúmenes, los permisos y los registros.

5. Comprobar persistencia y recuperación: crea un dato de prueba, verifica que se conserva tras recrear los servicios y documenta una restauración. No uses docker compose down --volumes durante esta prueba, porque eliminaría los volúmenes y podría borrar los datos.

   docker volume ls
   docker volume inspect proyecto_datos-db
   docker compose down
   docker compose up --detach
   docker compose ps
   

   Compose puede anteponer el nombre del proyecto al volumen declarado en el YAML; por eso proyecto_datos-db representa el nombre real que se haya encontrado en docker volume ls y debe sustituirse si el proyecto se llama de otra forma.

6. Cerrar la ficha: asigna a cada fila Conforme, Bloqueado o Excepción, adjunta la evidencia y registra qué debe corregirse antes de pasar a producción. Una restricción de coste también debe quedar visible: una instancia cloud, una IP pública, un disco o una transferencia pueden generar facturación aunque la aplicación sea pequeña.

Entorno de prácticas y entorno de producción

Una configuración que funciona en localhost no es automáticamente apta para producción. En producción hay que revisar, además, TLS, copias, actualización, monitorización, límites de recursos, control de acceso y procedimiento de vuelta atrás.

6. Buenas prácticas

Para trabajar este contenido con criterio, conviene aplicar estas buenas prácticas:

• Hacer requisitos verificables: escribe un valor esperado, una prueba y la evidencia que se conservará.
• Separar inventario y requisitos: el inventario describe lo que trae la aplicación; la ficha describe lo que debe ofrecer el entorno.
• Distinguir obligatorios y recomendados: así se sabe qué bloquea el despliegue y qué puede planificarse como mejora.
• Fijar versiones compatibles: registra etiquetas inmutables o digest y la combinación que se ha probado.
• Publicar lo mínimo: expón solo los puntos de entrada necesarios y deja las bases de datos en redes internas.
• Separar código, configuración y datos: usa imágenes versionadas, archivos de ejemplo sin secretos y almacenamiento persistente para los datos.
• Prever recuperación: un requisito de persistencia sin copia y restauración probadas está incompleto.
• Registrar excepciones: una desviación aceptada necesita responsable, motivo, fecha y condición para revisarla.

7. Errores frecuentes

Error frecuente	Por qué ocurre	Cómo evitarlo
Confundir estructura con requisitos	Se mezcla qué tiene la app con qué necesita el entorno	Mantén inventario y ficha separados
Dar por válida una guía antigua	Se copia documentación sin contrastar la versión	Comprueba el artefacto, manifest y entorno real
Publicar todos los puertos	Se usa la comodidad como criterio de red	Publica solo entradas necesarias y revisa el firewall
Usar la IP de un contenedor como configuración	Se olvida que puede cambiar al recrearlo	Usa el nombre DNS del servicio en la red interna
Poner credenciales en Compose o Git	Se busca una configuración rápida	Usa .env protegido o un gestor de secretos
Confundir Conforme con Pendiente	Se interpreta una fila sin comprobar como correcta	Define estados y exige una evidencia por fila
No comprobar permisos ni recuperación	El proceso arranca, pero falla al escribir o restaurar	Prueba con el usuario real y realiza una restauración
Probar solo desde el navegador	La interfaz responde, pero no se valida la cadena completa	Comprueba salud, logs, red, datos y versiones

8. Resumen

En este tema has aprendido que:

• los requisitos de implantación se extraen de documentación, artefactos, restricciones y características reales del entorno;
• una ficha rigurosa cubre sistema, software, red, configuración, almacenamiento, seguridad, operación y coste;
• los puertos publicados no son lo mismo que los puertos internos, y una aplicación no debe depender de IP efímeras de contenedores;
• las variables separan configuración y código, pero los secretos necesitan un mecanismo protegido;
• una evidencia fechada convierte una afirmación ambigua en una condición verificable;
• una aplicación solo está preparada cuando se han probado también la salud, la persistencia y la recuperación.

Idea clave

Describir los requerimientos de implantación no consiste en enumerar herramientas: consiste en demostrar que cada componente tiene un entorno compatible, una conexión controlada, unos datos protegidos y una forma de comprobarse y recuperarse.

9. Para seguir practicando

• Completa la ficha para WordPress con Docker Compose, separando requisitos obligatorios y recomendados.
• Contrasta requisitos de red, almacenamiento y recuperación en Guestbook.
• Revisa la práctica de Tomcat con Nginx y anota qué requisitos corresponden al servidor web y cuáles al servidor de aplicaciones.
• Compara tus decisiones con la introducción al despliegue de José Juan Sánchez.

Bibliografía y fuentes

• Normativa del módulo 0614.
• Docker Compose: variables de entorno.
• Docker Compose: redes.
• Docker: volúmenes.
• Docker Compose: healthcheck y dependencias.
• José Juan Sánchez: introducción al despliegue.
• Raúl Profesor: contenedores Docker.

Presentación

• DAW-U3.4 · Requisitos de implantación