==================================================== Procedimiento Generalizado de Despliegue y Operación ==================================================== Identificador Técnico: DOCS-GUIDE-004 Propósito ========= Este documento formaliza y estandariza el procedimiento integral de despliegue, actualización periódica y publicación de la Red de Espejos Comunitarios de Fundación MxOS. Describe el ciclo operativo desde la sincronización de paquetes upstream hasta la propagación inmutable en el enjambre de IPFS y el enclavillado selectivo en la infraestructura perimetral. Topología y Roles Operativos ============================ La arquitectura de publicación distribuye responsabilidades entre dos capas claramente diferenciadas: 1. **Nodo Central de Ingesta:** Máquina con almacenamiento masivo donde reside el árbol completo de paquetes en el directorio de preparación; ejecuta la ingesta en frío mediante filestore, gestiona el árbol en el Sistema Mutable de Archivos; administra la llave criptográfica Ed25519 y orquesta las réplicas. 2. **Nodo Perimetral Semilla, web0.mx-os.mx:** Servidor perimetral conectado a internet pública con dirección IPv4/IPv6 fija; expone el proxy inverso Nginx con certificados TLS; ejecuta una pasarela Kubo endurecida; enclavilla exclusivamente los activos web y metadatos; y sirve como punto de arranque e intercambio para clientes tradicionales y nodos de la comunidad. Requisitos del Sistema y Entorno ================================ El entorno de ejecución requiere la definición de variables estándar en el archivo de configuración ``nodo/config/etc/mirrors.env`` o ``/etc/mirrors.env``: .. code-block:: bash MIRRORS_STAGING_DIR="/home/renich/ipfs/staging" MIRRORS_DOMAIN="mirrors.mx-os.mx" MIRRORS_IPNS_KEY="mxos-mirrors" MIRRORS_LOCK_FILE="/tmp/mxos-repo-sync.lock" CF_ZONE_ID="" CF_API_TOKEN="" En el demonio local de Kubo, es indispensable habilitar el soporte de filestore para evitar la duplicación de datos en disco y activar la propagación rápida de IPNS mediante temas de suscripción: .. code-block:: bash ipfs config --json Experimental.FilestoreEnabled true ipfs config --json Ipns.UsePubsub true Ciclo Operativo de Despliegue ============================= Paso 1: Sincronización Upstream hacia Preparación ------------------------------------------------- La descarga diferencial de paquetes e índices de metadatos se ejecuta con ``rsync`` hacia el directorio local definido en ``MIRRORS_STAGING_DIR``. Para evitar colisiones entre tareas programadas o ejecuciones interactivas, el script adquiere un cerrojo exclusivo basado en el identificador de proceso: .. code-block:: bash ./nodo/bin/mxos-mirror.bash sync Durante este paso se actualizan los árboles de Fedora Releases, Fedora Updates, CentOS Stream 10 BaseOS/AppStream, grupos de interés especial y medios de instalación ISO. Paso 2: Generación de Activos Web y Metadatos --------------------------------------------- Antes de congelar el grafo de contenido, se compilan y copian los componentes de la interfaz de usuario: 1. Compilación del manual principal desde ``README.rst`` a formato HTML mediante pandoc. 2. Generación del portal interactivo ``index.html`` con enlaces a módulos, bitácora y visor de telemetría. 3. Copia de activos estáticos, imagen de portada ``cover.jpg`` y documentación generada hacia el directorio de preparación: .. code-block:: bash ./nodo/bin/mxos-mirror.bash html cp index.html README.html cover.jpg bitacora-cids.json "${MIRRORS_STAGING_DIR}/" rsync -a docs/_build/html/ "${MIRRORS_STAGING_DIR}/docs/" Paso 3: Ingesta Filestore y Estructuración en MFS ------------------------------------------------- Para no duplicar cientos de gigabytes en el bloque de almacenamiento de Kubo, la adición se ejecuta con la bandera ``--nocopy``. Kubo indexa las posiciones de bytes de los archivos en disco y genera los bloques y árboles Merkle-DAG sin copiar la carga útil: .. code-block:: bash ipfs add -r --nocopy --cid-version=1 --hash=sha2-256 "${MIRRORS_STAGING_DIR}" Posteriormente, el árbol se monta de manera limpia bajo la raíz del Sistema Mutable de Archivos: .. code-block:: bash ipfs files rm -r /mxos-root || true ipfs files cp "/ipfs/${CID_INGESTADO}" /mxos-root CID_ACTIVO=$(ipfs files stat --hash /mxos-root) Paso 4: Registro en la Bitácora Histórica ----------------------------------------- Cada publicación genera un identificador de contenido raíz inmutable y permanente. Dicho registro se incorpora cronológicamente en ``bitacora-cids.json`` para permitir a los administradores congelar repositorios en instantáneas anteriores o realizar auditorías forenses: .. code-block:: bash ./nodo/bin/mxos-bitacora.bash add "${CID_ACTIVO}" "${BYTES_TOTALES}" "Actualización periódica del catálogo" Paso 5: Publicación Mutable y Resolución ---------------------------------------- Para comunicar a los clientes el nuevo identificador de contenido raíz existen dos alternativas arquitectónicas: Estrategia Simplificada: DNSLink Apuntando a IPNS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Siguiendo las especificaciones del estándar de IPFS, un registro DNSLink puede asociarse permanentemente a una llave IPNS mutable en lugar de actualizarse con cada nuevo hash: .. code-block:: text _dnslink.mirrors.mx-os.mx. 300 IN TXT "dnslink=/ipns/k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v" Bajo este modelo: * El registro TXT en Cloudflare se configura una sola vez en la vida del dominio y nunca requiere modificaciones posteriores. * Se elimina la dependencia de credenciales, claves de API o límites de tasa de proveedores externos de DNS durante los ciclos de sincronización periódica. * El despliegue de cada nueva versión se limita a la firma y publicación criptográfica con la llave Ed25519: .. code-block:: bash ipfs name publish --key=mxos-mirrors --lifetime=720h --ttl=5m "/ipfs/${CID_ACTIVO}" * Al mantener activada la opción ``Ipns.UsePubsub true`` en los nodos participantes, la actualización se propaga en submilisegundos a través de la red de multidifusión sin las demoras habituales de la tabla hash distribuida. Estrategia Alternativa: DNSLink Directo a CID Raíz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Si se requiere eliminar por completo la fase de resolución de nombres de IPNS en clientes externos que no disponen de soporte PubSub, se actualiza el registro TXT en Cloudflare apuntando directamente al prefijo canónico ``dnslink=/ipfs/${CID_ACTIVO}``: .. code-block:: bash ./nodo/bin/mxos-dnslink-update.bash "${CID_ACTIVO}" Paso 6: Replicación y Enclavillado Selectivo en web0 ----------------------------------------------------- Para garantizar alta disponibilidad sin desbordar la capacidad de almacenamiento del servidor perimetral, el nodo ``web0.mx-os.mx`` enclavilla exclusivamente la interfaz web y los metadatos; los paquetes RPM e imágenes ISO se transfieren dinámicamente bajo demanda desde el nodo central o desde los nodos guardianes de la comunidad vía Bitswap: .. code-block:: bash ssh root@web0.mx-os.mx "ipfs --api=/ip4/127.0.0.1/tcp/5001 pin add \ ${CID_ACTIVO}/index.html \ ${CID_ACTIVO}/README.html \ ${CID_ACTIVO}/cover.jpg \ ${CID_ACTIVO}/docs \ ${CID_ACTIVO}/bitacora-cids.json; \ systemctl restart ipfs" El reinicio del servicio de IPFS en ``web0`` purga la memoria intermedia interna de resolución de nombres, asegurando que las solicitudes entrantes resuelvan inmediatamente la nueva instantánea. Paso 7: Verificación del Servicio --------------------------------- Una vez concluida la replicación, se valida la disponibilidad mediante consultas directas a los encabezados HTTP: .. code-block:: bash # Verificación en la pasarela local curl -s -I "http://mirrors.mx-os.mx.ipns.localhost:8080/" | grep -E "HTTP|Etag|X-Ipfs-Roots" # Verificación en el dominio público seguro curl -s -I "https://mirrors.mx-os.mx/" | grep -E "HTTP|etag|x-ipfs-roots" Ambas respuestas deben reportar código HTTP 200 y reflejar el identificador de contenido raíz recién generado en la cabecera ``etag`` o ``x-ipfs-roots``. Diagnóstico y Procedimientos de Contingencia ============================================ Resolución de Errores 500 por Discrepancia en Filestore ------------------------------------------------------- Si un archivo indexado mediante filestore sufre modificaciones de contenido o longitud en el sistema de archivos local antes de generar un nuevo CID, Kubo detectará la discrepancia entre el hash esperado y los bytes en disco, respondiendo con error interno HTTP 500. Para remediar esta condición: 1. Regenerar el árbol en el directorio de preparación con la instrucción ``./nodo/bin/mxos-mirror.bash html``. 2. Realizar la adición con ``ipfs add -r --nocopy`` para recalcular los hashes de bloques alterados. 3. Actualizar la referencia en MFS y reiniciar el demonio de IPFS con ``systemctl --user restart ipfs`` para vaciar la memoria intermedia de bloques y nombres. Gestión y Liberación de Candados Huérfanos ------------------------------------------ Si un proceso de sincronización termina de manera abrupta por interrupción de red o reinicio del sistema, el archivo de cerrojo puede bloquear ejecuciones futuras. Para diagnosticar y depurar el estado del candado: .. code-block:: bash # Consultar si el proceso asociado al candado continúa activo ./nodo/bin/mxos-mirror.bash lock-status # Eliminar el archivo de cerrojo huérfano ./nodo/bin/mxos-mirror.bash lock-clean Respaldo de la Identidad Criptográfica IPNS ------------------------------------------- La llave privada Ed25519 que firma las actualizaciones de ``mxos-mirrors`` es el núcleo de soberanía de la red. Debe respaldarse de forma segura fuera del servidor: .. code-block:: bash # Exportar la llave a un archivo blindado ipfs key export mxos-mirrors -o mxos-mirrors.key chmod 400 mxos-mirrors.key Para restaurar la identidad en un nodo de contingencia: .. code-block:: bash ipfs key import mxos-mirrors mxos-mirrors.key