3.9.-Documentación reproducible de la instalación

3.9. Documentación reproducible de la instalación

Idea principal

Una guía técnica de despliegue no es un relato de lo que una persona hizo una vez. Es un documento versionado, verificable y seguro que explica el entorno, las decisiones, los comandos, la configuración, las pruebas y la recuperación necesaria para que otra persona pueda repetir el proceso.

Decimos que está versionado cuando sus cambios quedan registrados, por ejemplo, en Git. Decimos que es verificable cuando incluye datos y pruebas que permiten comprobar si cada paso ha funcionado. Así, la guía no depende de la memoria de quien la escribió.

La documentación se empieza durante la instalación, no al final de la práctica. Registrar versiones, decisiones y errores mientras ocurren evita reconstruir de memoria comandos que quizá dependían de un estado concreto del sistema. Este tema reúne las evidencias generadas en los criterios anteriores y las convierte en una guía operativa.

La relación normativa exclusiva de este documento es:

Código	Descripción
RA1	Implanta arquitecturas web analizando y aplicando criterios de funcionalidad.
CE i	Se han documentado los procesos de instalación y configuración realizados sobre los servidores web, de aplicaciones y sobre tecnologías de virtualización en la nube y en contenedores.

Este apunte cierra el recorrido de los puntos anteriores. Por eso no sustituye a la teoría de Nginx, Tomcat, Docker o las pruebas: explica cómo reunir sus decisiones y evidencias en un documento operativo. Una guía que solo enumera comandos no demuestra por sí sola una documentación reproducible; también debe indicar sobre qué entorno se ejecutan, qué resultado se espera y cómo se comprueba.

Parte documentada	Evidencia que conviene conservar
Servidor web	Versión, archivo de configuración, validación y recarga de Nginx.
Servidor de aplicaciones	Versión de Tomcat, aplicación desplegada, contexto y logs.
Virtualización o nube	Imagen o instancia, recursos, red, puertos, volúmenes y proveedor.
Integración	Recorrido cliente → Nginx → Tomcat → aplicación y prueba de extremo a extremo.

Qué deberías saber al terminar

Deberías poder:

• estructurar una guía de instalación desde el contexto hasta la verificación;
• documentar comandos, archivos, versiones y decisiones sin publicar secretos;
• revisar una guía con otra persona y corregir los pasos que no sean reproducibles.

Mapa del tema

Definiremos el objetivo de una guía, describiremos el entorno, documentaremos la instalación y la configuración, añadiremos pruebas y cerraremos con una revisión de reproducibilidad.

1. Documentar para otra persona

Una documentación técnica tiene una persona lectora y un objetivo concreto. En este caso, debe permitir que alguien con los conocimientos previos indicados pueda preparar el entorno, instalar los componentes, aplicar la configuración y comprobar el resultado.

Reproducibilidad

Capacidad de obtener un resultado equivalente al repetir un proceso con las mismas condiciones, versiones, entradas y pasos documentados.

La reproducibilidad no significa que todos los entornos sean idénticos. Si una instancia cloud tiene una dirección IP diferente, la guía debe indicar dónde se introduce ese valor y qué parte de la configuración depende de él.

Una guía debe distinguir tres tipos de información:

• hechos del entorno: sistema operativo, versiones, nombres y recursos;
• acciones: comandos, archivos editados y órdenes de inicio o parada;
• resultados: pruebas ejecutadas, evidencias, incidencias y decisiones.

También conviene declarar el contrato de la guía antes de empezar. Este contrato evita que una persona lectora tenga que adivinar para quién está escrita o qué resultado se considera correcto:

Dato	Ejemplo	Por qué es necesario
Alcance	Publicar catalogo.war con Nginx y Tomcat en un entorno de aula.	Delimita lo que la guía resuelve y lo que queda fuera.
Persona destinataria	Alumnado que conoce Linux, Docker y HTTP básico.	Permite decidir qué conceptos hay que explicar.
Estado inicial	Ubuntu 24.04, Docker instalado y repositorio clonado.	Evita pasos implícitos.
Resultado válido	curl devuelve HTTP 200 en /catalogo/ y los datos de prueba persisten.	Convierte «funciona» en una condición comprobable.
Límites	No describe un despliegue de producción ni gestiona credenciales reales.	Evita reutilizar el ejemplo fuera de su contexto.

Reproducible no significa idéntico

Dos ejecuciones pueden tener nombres de host, direcciones IP o fechas diferentes y seguir siendo reproducibles. Lo importante es declarar qué valores cambian, dónde se introducen y qué propiedades deben mantenerse: versiones compatibles, puertos accesibles, servicios conectados y pruebas superadas.

2. Estructura de una guía técnica

Una estructura útil para esta unidad es:

Sección	Pregunta que responde
Alcance y objetivo	¿Qué se instala y qué queda fuera?
Requisitos previos	¿Qué necesita la persona antes de empezar?
Arquitectura	¿Qué componentes existen y cómo se comunican?
Entorno y versiones	¿Sobre qué sistema y versiones se ha validado?
Instalación	¿Qué comandos preparan los servicios?
Configuración	¿Qué archivos y parámetros se cambian?
Arranque y parada	¿Cómo se administra el ciclo de vida?
Pruebas	¿Cómo se demuestra que funciona?
Incidencias	¿Qué problemas aparecieron y cómo se resolvieron?
Seguridad y recuperación	¿Cómo se protegen secretos y datos?
Mantenimiento	¿Cómo se actualiza o deshace el despliegue?

La guía puede mantenerse como documentación como código (docs-as-code): ficheros Markdown, Compose y configuración en el mismo repositorio que el despliegue. Así se puede revisar cada cambio, asociarlo a una versión y recuperar una guía anterior junto con la configuración que describía. No es obligatorio usar una herramienta concreta, pero sí mantener una relación clara entre la versión del software y la versión de la documentación.

Como mínimo, cada versión validada debería identificar:

• versión o etiqueta del documento, por ejemplo v1.2;
• fecha de validación y persona o equipo que la realizó;
• versión de la aplicación, imágenes y herramientas principales;
• commit, etiqueta o referencia del repositorio que se ha probado;
• cambios desde la revisión anterior y procedimiento de vuelta atrás.

Cabecera de una guía de despliegue

Guía: catálogo web - instalación con Compose
Documento: v1.2
Repositorio: commit 4f8c2a1
Validada: 2026-11-01
Entorno: Ubuntu 24.04 amd64, Docker Engine 27.x, Compose v2.x
Resultado: HTTP 200 en /catalogo/ y persistencia verificada

El índice debe reflejar el recorrido real. No conviene ocultar pasos importantes en una captura de pantalla: una imagen puede servir como evidencia, pero no sustituye al comando ni a su explicación.

3. Registrar el entorno y la arquitectura

Empieza con una ficha que se pueda comparar entre ejecuciones:

Proyecto: catálogo web
Fecha de validación: 2026-11-01
Sistema anfitrión: Ubuntu 24.04 amd64
Motor: Docker 27.x y Compose v2.x
Servicios: Nginx, Tomcat y MariaDB
Entrada publicada: TCP 80
Red interna: catalogo_default
Persistencia: volumen datos-db
Responsable de la validación: equipo de aula

La versión 27.x es un ejemplo de formato. En una guía que deba reproducirse sin ambigüedad se anota el número exacto y se indica cómo obtenerlo. También se conserva la arquitectura del proyecto, no solo el nombre de las herramientas:

catalogo/
├── compose.yaml
├── .env.example
├── .gitignore
├── nginx/
│   └── default.conf
├── app/
│   └── catalogo.war
└── docs/
    ├── instalacion.md
    └── cambios.md

El archivo .env.example documenta los nombres y ejemplos no sensibles; el .env real se crea en cada entorno y no se versiona. La carpeta docs/ debe explicar los archivos que intervienen, no ser un lugar para guardar una copia desactualizada de la configuración.

uname -a
docker version
docker compose version

Una guía reproducible conserva contexto, acciones, resultados y evidencias desde la preparación hasta el mantenimiento.

El mismo procedimiento puede validarse de forma progresiva en desarrollo, pruebas y producción; cada cambio de entorno debe quedar identificado.

Para una máquina virtual o un proveedor cloud, añade a la ficha los datos que pueden cambiar el resultado:

Entorno	Datos que documentar
Máquina virtual	Hipervisor, imagen base y su identificador, CPU, memoria, disco, red, instantánea y fecha de creación.
Instancia cloud	Proveedor, región, tipo de instancia, imagen, grupo de seguridad o firewall, IP o DNS, disco y política de apagado.
Contenedores	Versiones de Docker y Compose, imágenes y etiquetas o digest, red, puertos publicados, montajes y volúmenes.

Un digest es la huella, normalmente sha256:..., que identifica el contenido exacto de una imagen. Una etiqueta como nginx:1.27 puede recibir actualizaciones; el digest permite demostrar qué contenido se validó. No hace falta copiarlo en todos los ejercicios, pero sí registrarlo cuando la reproducibilidad del entorno sea crítica.

No incluyas claves privadas, tokens ni datos de facturación. Basta con indicar qué cuenta o responsable proporciona el recurso y cómo se obtiene de forma segura.

El diagrama debe mostrar el flujo de las peticiones y no solo los nombres de los productos:

flowchart LR
  U["Cliente"] -->|"HTTPS o HTTP de laboratorio"| N["Nginx<br/>entrada pública"]
  N -->|"red interna"| T["Tomcat<br/>aplicación Java"]
  T -->|"conexión interna"| DB["Base de datos"]
  DB --> V["Volumen persistente"]
  N --> NL["logs Nginx"]
  T --> TL["logs Tomcat"]

Junto al diagrama se indican puertos, nombres de servicio, rutas de montajes y qué componente administra cada recurso. Una ruta de montaje relaciona una carpeta o volumen del equipo con una carpeta dentro de un contenedor. Si existe un proveedor cloud, también se documentan región, firewall, tipo de instancia y responsable de la cuenta.

4. Documentar comandos y archivos

Cada comando debe aparecer con su propósito, su contexto y un resultado esperado. No basta con copiar un historial de terminal que contenga rutas personales o credenciales.

# Validar la configuración antes de crear recursos
docker compose config

# Iniciar los servicios del proyecto
docker compose up --detach

# Consultar el estado después del arranque
docker compose ps

# Detener servicios sin borrar los volúmenes
docker compose down

La guía debe explicar también qué significa cada orden y qué no garantiza. Por ejemplo, docker compose ps informa del estado de los contenedores, pero no demuestra que una petición haya atravesado Nginx y llegado a Tomcat. La verificación funcional se documenta aparte.

Un fragmento mínimo y legible de la configuración podría ser:

services:
  app:
    image: tomcat:9.0-jdk17-temurin
    expose:
      - "8080"  # Solo accesible dentro de la red de Compose
    volumes:
      - ./app/catalogo.war:/usr/local/tomcat/webapps/catalogo.war:ro

  web:
    image: nginx:1.27
    ports:
      - "${HTTP_PORT:-8080}:80"  # host:contenedor
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app

En este ejemplo, expose no publica Tomcat en el anfitrión y :ro impide que el contenedor modifique el WAR o la configuración montada. depends_on expresa un orden de arranque, pero por sí solo no demuestra que Tomcat esté listo para atender peticiones. La guía debe incluir una comprobación de disponibilidad y, si el proyecto lo necesita, un healthcheck compatible con la imagen elegida.

Una forma útil de redactar cada paso es relacionarlo con su resultado:

Acción documentada	Resultado esperado	Evidencia
docker compose config	La configuración se resuelve sin errores.	Salida del comando o estado correcto.
docker compose up --detach	Se crean app y web sin errores de arranque.	docker compose ps y logs iniciales.
curl --include http://localhost:8080/catalogo/	La respuesta contiene el código y el contenido previstos.	Cabeceras y muestra no sensible.
docker compose logs --since=10m web app	Se localizan la petición y el despliegue de la aplicación.	Extracto con fecha y servicio.
Recrear el servicio de datos sin borrar el volumen	Los datos definidos como persistentes se conservan.	Comparación antes y después.

Este patrón transforma un listado de comandos en un procedimiento que otra persona puede auditar.

Para cada archivo de configuración documenta:

• ruta dentro del proyecto o del contenedor;
• propósito de cada bloque importante;
• valores que pueden cambiar entre entornos;
• permisos y propietario necesarios;
• procedimiento de validación y de recarga;
• versión del formato y fecha de la última revisión.

Para que la descripción no quede desligada del archivo, usa una tabla de trazabilidad como esta:

Archivo o recurso	Lo que controla	Cómo se valida	Qué cambia entre entornos
compose.yaml	Servicios, red y montajes.	docker compose config.	Etiquetas de imagen y límites de recursos.
nginx/default.conf	Entrada pública y proxy al backend.	nginx -t dentro del servicio o una validación equivalente.	Dominio, TLS y rutas públicas.
app/catalogo.war	Versión desplegada de la aplicación.	Petición al contexto y revisión de logs de Tomcat.	Artefacto o versión de la entrega.
Volumen datos-db	Datos que deben sobrevivir al ciclo del contenedor.	Restauración de una copia y consulta de prueba.	Nombre y ubicación según el entorno.

Cuando un valor sea específico del entorno, utiliza un marcador explícito como DOMINIO_APLICACION y explica cómo sustituirlo. Eso es más útil que escribir una dirección real sin contexto.

4.1. Proteger secretos y datos sensibles

Una guía reproducible no necesita publicar contraseñas, claves privadas, tokens, cookies, certificados privados ni datos personales. Un secreto es un dato que permite acceder a un servicio, como una contraseña o una clave. La guía puede documentar el nombre de una variable, el tipo de valor y el mecanismo seguro que la suministra:

Variable	Propósito	Ejemplo seguro	Origen real
DB_HOST	Nombre del servicio de datos	db	Configuración del entorno
DB_NAME	Base de datos de la aplicación	catalogo	Archivo de configuración
DB_PASSWORD	Credencial de conexión	<secreto>	Gestor de secretos
PUBLIC_HOST	Nombre público	app.example	DNS o ficha del entorno

Usa .env.example para los nombres y valores ficticios, añade .env a las reglas de exclusión y revisa el historial de Git. Si se publica una credencial por error, no basta con borrarla del archivo actual: hay que revocarla y regenerarla.

4.2. Diferenciar entornos sin duplicar la guía

Una misma arquitectura puede tener valores distintos en desarrollo, pruebas y producción. Documenta la diferencia explícitamente, pero evita copiar tres guías casi iguales:

Valor	Desarrollo	Pruebas	Producción
Publicación HTTP	localhost:8080	DNS interno de pruebas	Dominio público con HTTPS
Datos	Volumen efímero con datos sintéticos	Copia anonimizada	Volumen gestionado y copia probada
Logs	Salida local de Compose	Retención limitada	Sistema centralizado y alertas
Actualización	Manual y observable	Validada por la matriz de pruebas	Revisada, programada y con rollback

Si se usan archivos Compose adicionales, la guía debe indicar el orden en que se combinan y qué propiedad sobrescribe cada uno. Por ejemplo:

docker compose -f compose.yaml -f compose.pruebas.yaml config
docker compose -f compose.yaml -f compose.pruebas.yaml up --detach

Primero valida la configuración resultante con config; así se detecta una variable ausente o un puerto duplicado antes de crear recursos.

El registro de cambios debe explicar el motivo, no solo enumerar archivos:

Versión	Cambio	Motivo	Validación	Recuperación
v1.2	Actualización de Tomcat	Corregir una versión sin soporte en pruebas.	Matriz T01–T06 y revisión de logs.	Volver a la etiqueta v1.1 y repetir T04–T06.

5. Incluir inicio, parada, pruebas y recuperación

La guía debe explicar el ciclo completo, incluyendo las operaciones que no se ejecutan todos los días:

1. Preparación: comprobar requisitos, versiones, red y almacenamiento.

2. Instalación: ejecutar los comandos en el orden indicado y conservar sus resultados relevantes.

3. Configuración: editar o montar los archivos y validar su sintaxis.

4. Arranque: iniciar los servicios y esperar las condiciones de salud descritas.

5. Prueba: ejecutar la matriz de comprobaciones y guardar evidencias.

6. Parada y actualización: detener o recrear según el procedimiento seguro, sin borrar datos por accidente.

7. Recuperación: restaurar una copia o volver a la versión anterior y repetir la prueba que demuestra que la recuperación funciona.

Volver a una versión anterior se denomina rollback. Se utiliza cuando una actualización provoca un problema y necesitamos recuperar un estado conocido que funcionaba.

La guía debe enlazar el resultado de las pruebas con el procedimiento, pero no debe afirmar que una copia es válida si nunca se ha probado su restauración.

5.1. Revisar la reproducibilidad

La revisión más eficaz la realiza otra persona en un entorno limpio. Quien escribió la guía puede completar pasos de forma automática y no detectar datos implícitos. La persona revisora anota:

Comprobación	Resultado	Observación
Requisitos previos suficientes	Pendiente	¿Falta una herramienta o permiso?
Versiones identificadas	Pendiente	¿Se puede obtener el número exacto?
Comandos ejecutables	Pendiente	¿Funcionan desde un directorio indicado?
Secretos protegidos	Pendiente	¿Hay valores reales en ejemplos o capturas?
Pruebas repetibles	Pendiente	¿Se conoce el resultado esperado?
Recuperación descrita	Pendiente	¿Se puede volver a un estado válido?

Una guía madura incluye fecha de validación y un registro de cambios. Si una instrucción deja de ser válida por una actualización, se corrige la guía o se fija la versión que la hacía funcionar.

5.2. Registrar una incidencia y su recuperación

Los fallos también forman parte de la documentación. Ocultarlos produce una guía engañosa; describirlos permite reconocerlos y recuperar el servicio. Un registro breve debe separar el hecho observado de la hipótesis y de la acción:

ID: INC-002
Momento: 2026-11-01 11:20
Síntoma: Nginx devuelve HTTP 502 en /catalogo/
Contexto: el contenedor web está activo; Tomcat se acaba de recrear
Evidencia: docker compose ps y logs de web y app
Hipótesis: el proxy intenta usar un nombre de servicio que no coincide
Acción: corregir upstream en default.conf y validar nginx -t
Resultado: HTTP 200 después de recargar Nginx
Recuperación: restaurar el commit anterior si T04 vuelve a fallar
Estado: cerrada

La guía no debe afirmar que existe recuperación solo porque se ha escrito el comando. Hay que probarla: restaurar la versión anterior o una copia en un entorno controlado, repetir la prueba que falló y registrar el resultado. Así se distingue una copia existente de una copia recuperable.

6. Buenas prácticas

• Documentar mientras se trabaja: registra decisiones y resultados cuando todavía conoces el contexto.
• Versionar la configuración: guarda Compose, Nginx y plantillas sin secretos en un repositorio con cambios revisables.
• Usar resultados esperados: acompaña cada acción con una comprobación observable.
• Separar valores variables: utiliza marcadores, variables de entorno o secretos en lugar de copiar datos de una máquina concreta.
• Fijar dependencias críticas: registra etiquetas y, cuando el entorno lo requiera, el digest de las imágenes para evitar que una etiqueta mutable cambie el resultado sin que la guía lo refleje.
• Aplicar el mínimo privilegio: documenta qué permisos necesita cada paso y evita ejecutar todo como root sin una razón técnica.
• Cuidar las evidencias: acompaña las capturas con fecha, entorno, resultado esperado y texto alternativo; la imagen no debe ser la única explicación.
• Validar desde cero: pide a otra persona que siga la guía y corrige los pasos implícitos.

7. Errores frecuentes

Error frecuente	Por qué ocurre	Cómo evitarlo
Documentar solo el resultado final	Se escribe cuando ya no se recuerdan los pasos	Registra acciones y evidencias durante la instalación
Copiar un historial de terminal sin limpiar	Se confían comandos y datos locales	Reescribe con propósito, contexto y marcadores seguros
Omitir versiones	Se supone que el entorno es universal	Anota versiones exactas y fecha de validación
Publicar contraseñas en capturas	Se busca demostrar que la configuración funciona	Oculta secretos y usa valores ficticios
No explicar cómo deshacer cambios	Solo se piensa en el camino feliz	Incluye parada, copia, restauración y rollback (vuelta a una versión anterior)
Confundir una captura con una prueba reproducible	La imagen no contiene el procedimiento	Añade comando, resultado esperado y contexto
Usar latest sin registrar la versión real	Se confía en que la etiqueta siempre representa lo mismo	Fija una versión validada y registra el digest cuando sea necesario
Confundir depends_on con disponibilidad	Se interpreta el orden de arranque como salud	Comprueba el servicio y espera su condición de disponibilidad
Ejecutar down --volumes como limpieza habitual	Se copia una orden destructiva sin analizarla	Advierte que elimina volúmenes y exige una copia o confirmación previa
No indicar desde qué directorio se ejecuta	El autor conoce rutas que la persona lectora no	Incluye cd, rutas relativas y requisitos de permisos

8. Resumen

En este tema has aprendido que:

• una guía reproducible describe contexto, acciones, resultados y límites;
• la arquitectura, las versiones, los archivos, los comandos y el ciclo de vida deben quedar conectados;
• la documentación debe ser útil sin revelar secretos ni datos personales;
• otra persona debe poder validar la guía desde un entorno limpio y comprobar la recuperación.

Idea clave

Documentar un despliegue es convertir una experiencia concreta en un procedimiento verificable, seguro y mantenible por el equipo.

9. Para seguir practicando

• Completa una guía de Tomcat con Nginx usando Docker Compose incluyendo versiones, comandos y pruebas.
• Documenta el ciclo de persistencia y recuperación de WordPress con Compose.
• Consulta el material publicado sobre documentación de la unidad 1.
• Intercambia la guía con otra persona: debe preparar un directorio limpio, ejecutar los pasos sin recibir instrucciones orales y anotar cada dato que falte. Después, actualiza la guía y repite la prueba de extremo a extremo.

Bibliografía y fuentes

• Normativa del módulo 0614.
• Documentación oficial de Docker Compose.
• Documentación oficial de Nginx.
• Documentación oficial de Apache Tomcat.
• Material local sobre documentación.

Presentación

Presentación DAW-U3.9 · Documentación reproducible de la instalación.