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:

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="<identificador_de_zona_cloudflare>"
CF_API_TOKEN="<token_autorizado_dns>"

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:

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:

./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:

./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:

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:

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:

./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:

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:

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:

# 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:

# 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:

# 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:

ipfs key import mxos-mirrors mxos-mirrors.key