========================================================
Red de Espejos Comunitarios de Software Libre sobre IPFS
========================================================

Infraestructura de distribución soberana, descentralizada y de alta resiliencia para distribuciones Linux de la familia RPM, operada por la `Fundación MxOS`_ bajo el dominio canónico ``mirrors.mx-os.mx``.

.. _Fundación MxOS: https://mx-os.mx

.. contents:: Índice de Contenidos
   :depth: 2
   :backlinks: none

Propósito y Misión
==================
Históricamente, los usuarios e instituciones en México y Latinoamérica han dependido de espejos universitarios aislados o enlaces transfronterizos hacia redes de entrega de contenido comerciales en Estados Unidos. Esta dependencia genera latencia, costos recurrentes de transferencia y vulnerabilidad ante caídas de enlaces internacionales.

La red de espejos de MxOS replantea la entrega de paquetes utilizando el Sistema de Archivos Interplanetario (IPFS). Al emplear direccionamiento por contenido y distribución entre pares (P2P), el espejo se convierte en una red colaborativa donde cualquier integrante de la comunidad o institución académica puede donar almacenamiento y ancho de banda local, deduplicando transferencias y acelerando descargas dentro de redes locales o nacionales.

Aviso de Fase Experimental
==========================
Este proyecto se encuentra actualmente en **fase de experimentación activa y prueba de concepto**. Operamos bajo una arquitectura de guerrilla diseñada para maximizar la soberanía sin requerir grandes presupuestos de infraestructura:

* La ingesta inicial y el almacenamiento de paquetes residen en estaciones de trabajo y nodos comunitarios locales.
* El gateway público oficial reside en HOBOPS.IO bajo el dominio ``ipfs.mx-os.mx``, accesible también mediante ``gateway.ipfs.mx-os.mx``; opera estrictamente como un punto de acceso efímero y proxy inverso sin almacenamiento permanente ni pineo.
* Convocamos a la comunidad técnica a probar las descargas, reportar anomalías y sumarse como nodos guardianes pioneros para evaluar el rendimiento real de Bitswap en conexiones residenciales y académicas.

Servicios y Dominios Públicos: ipfs.mx-os.mx y mirrors.mx-os.mx
==============================================================
Fundación MxOS opera dos servicios web públicos con responsabilidades y alcances claramente delimitados:

Úsanos de gateway de IPFS: ipfs.mx-os.mx
----------------------------------------
El dominio ``ipfs.mx-os.mx`` (junto con su alias ``gateway.mx-os.mx``) es la **pasarela pública y abierta de IPFS** de Fundación MxOS, alojada sobre la infraestructura soberana de HOBOPS.IO.

* **Propósito:** Ofrecer a cualquier usuario, estudiante, desarrollador, colectivo o proyecto un punto de acceso HTTP/HTTPS neutral, abierto y sin costo para resolver y descargar cualquier contenido publicado en la red global IPFS, pertenezca o no a Fundación MxOS.
* **Resolución universal de contenido:**
  * **Por identificador de contenido (CID):** ``https://ipfs.mx-os.mx/ipfs/<CID>`` permite descargar cualquier bloque, archivo o directorio UnixFS existente en el enjambre global.
  * **Por sistema de nombres interplanetario (IPNS):** ``https://ipfs.mx-os.mx/ipns/<nombre-o-llave>`` resuelve registros mutables basados en llaves Ed25519 o registros DNSLink.
* **Casos de uso e integración:**
  * **Extensión IPFS Companion:** Configura ``ipfs.mx-os.mx`` como tu pasarela pública preferida en Firefox, Chromium, Chrome o Brave para navegar contenidos descentralizados de forma transparente.
  * **Descargas directas en consola:** Utiliza ``curl`` o ``wget`` para obtener paquetes o artefactos de la red IPFS sin necesidad de instalar software adicional localmente:

    .. code-block:: bash

       curl -sL https://ipfs.mx-os.mx/ipfs/bafybeicg2abb... -o paquete.tar.gz

* **Naturaleza operativa:** Opera estrictamente como un proxy inverso de alta velocidad y acceso efímero. No enclavilla (*pin*) contenido de terceros ni ofrece almacenamiento persistente; actúa como pasarela de tránsito entre la web convencional y el enjambre de Bitswap.

El espejo de software libre de Fundación MxOS: mirrors.mx-os.mx
---------------------------------------------------------------
El dominio ``mirrors.mx-os.mx`` es el **portal web canónico y catálogo curado de distribución** de paquetes y medios de instalación de software libre de Fundación MxOS.

* **Propósito:** Mostrar nuestro espejo oficial de software libre, exhibir las notas de liberación y avisos técnicos agregados por la fundación, proveer instrucciones paso a paso para configurar gestores de paquetes (DNF/DNF5), ofrecer guías de enclavillado granular para operadores voluntarios y presentar el observatorio de salud en tiempo real (`Vigía`_).
* **Contenido alojado en el espejo:**
  * Repositorios completos de **Fedora Linux** (versiones 43, 44 y 45 para arquitectura ``x86_64``, abarcando imágenes netinst ISO y paquetería Everything).
  * Repositorios completos de **CentOS Stream 10** (BaseOS, AppStream, CRB, HighAvailability, NFV, RT y todos los repositorios SIG adicionales: extras, virtualización, módulos de kernel, mensajería, almacenamiento y hyperscale).
  * Directorio comunitario de custodios soberanos verificables (``guardianes.json``).
  * Tablero interactivo de observabilidad y cartografía territorial P2P (``/vigia/``).
  * Notas de liberación y documentación técnica añadida por la fundación.
* **Acceso multimodal:**
  * **Vía Web estándar:** Puedes navegarlo en cualquier explorador convencional ingresando a `https://mirrors.mx-os.mx <https://mirrors.mx-os.mx>`_.
  * **Vía IPFS nativo:** Accesible mediante el protocolo descentralizado en ``ipfs://mirrors.mx-os.mx`` o la ruta UnixFS ``/ipns/mirrors.mx-os.mx``.

Arquitectura y Principios de Operación
======================================
El sistema opera sobre cinco pilares técnicos:

1. **Direccionamiento por contenido inmutable:** Cada archivo, paquete RPM y metadato se divide en bloques criptográficos referenciados por su identificador de contenido (CID). Si dos versiones comparten paquetes idénticos, estos se deduplican en el almacenamiento global.
2. **Distribución entre pares con Bitswap:** Al solicitar un paquete, el demonio Kubo lo descarga simultáneamente de todos los nodos guardianes disponibles que lo posean en la red local o internet (puerto 4001 TCP/UDP).
3. **Puntero canónico con DNSLink:** Para evitar lidiar con hashes cambiantes en cada sincronización, el dominio ``mirrors.mx-os.mx`` cuenta con registros TXT DNSLink (``_dnslink.mirrors.mx-os.mx``) que apuntan al CID raíz más reciente con una propagación de 300 segundos.
4. **Puente HTTP para compatibilidad universal:** Quienes no cuenten con un nodo IPFS pueden consumir el espejo directamente a través de HTTP/HTTPS mediante el terminador web que reenvía peticiones hacia el enjambre.
5. **Observabilidad y telemetría comunitaria con Vigía:** Monitoreo descentralizado en tiempo real (`mirrors.mx-os.mx/vigia/`_) que audita la disponibilidad de cada módulo, la latencia y la distribución territorial de los nodos guardianes sin recolectar telemetría privada de los usuarios.

Vigía: Observabilidad y Cartografía del Enjambre P2P
====================================================
La salud, redundancia territorial y disponibilidad de los repositorios no es una caja negra: es auditable abiertamente por cualquier integrante de la comunidad en tiempo real mediante el tablero oficial **Vigía**:

* **Acceso web interactivo:** `mirrors.mx-os.mx/vigia/`_
* **Directorio estructurado de custodios:** Tabla responsiva con columnas canónicas: ``Rol``, ``Custodio``, ``Módulos custodiados``, ``Ubicación territorial`` y ``Afiliación``.
* **Copiado de identidad criptográfica con un clic:** Cada identificador de par (Peer ID / DI) incluye un botón de copiado directo con confirmación visual instantánea.
* **Filtrado reactivo por módulos:** Pulsar sobre cualquier etiqueta de módulo en la tabla filtra los custodios en tiempo real, activa un indicador destacado en la cabecera y muestra una barra de filtrado con botón de limpieza inmediata.
* **Cartografía soberana:** Muestra el número de guardianes por módulo (BaseOS, AppStream, Everything, ISOs), ubicación geográfica aproximada y organizaciones de red.
* **Interfaces de integración y telemetría:**

  * Instantánea estática en el catálogo: `https://mirrors.mx-os.mx/vigia/telemetry.json <https://mirrors.mx-os.mx/vigia/telemetry.json>`_
  * API REST en tiempo real del demonio Vigía: ``/api/v1/telemetry``
  * Exportador de métricas en formato estándar de Prometheus: ``/metrics``

.. _mirrors.mx-os.mx/vigia/: https://mirrors.mx-os.mx/vigia/

Inicio Rápido de Colaboración: Enclavillado de Repositorios
===========================================================
El objetivo fundamental de la red de espejos de MxOS es la soberanía y la resiliencia comunitaria: la infraestructura no depende de servidores centrales, sino del **enclavillado (pineo)** colaborativo. Cada usuario, institución o laboratorio aloja localmente los repositorios que mejor le parezca y comparte bloques con su red local e internet mediante intercambio entre pares (P2P).

En cinco pasos directos puedes configurar tu equipo como nodo guardián:

Paso 1: Instalación de Kubo
---------------------------
Kubo se encuentra empaquetado para Fedora y CentOS Stream en el repositorio Copr de MxOS:

.. code-block:: bash

   # Habilitar repositorio Copr e instalar paquete
   sudo dnf copr enable renich/kubo
   sudo dnf install kubo

Paso 2: Inicialización y servicio systemd
-----------------------------------------
Se recomienda operar Kubo en modo de usuario no privilegiado (rootless):

.. code-block:: bash

   # Inicializar almacén en ~/.ipfs
   ipfs init

   # Habilitar e iniciar servicio persistente de usuario
   systemctl --user enable --now ipfs.service

Paso 3: Apertura de puerto del enjambre libp2p
----------------------------------------------
Para permitir que otros nodos descarguen bloques desde tu equipo, abre el puerto 4001:

.. code-block:: bash

   # Abrir puerto de enjambre libp2p (TCP y UDP)
   sudo firewall-cmd --permanent --add-port=4001/tcp
   sudo firewall-cmd --permanent --add-port=4001/udp
   sudo firewall-cmd --reload

Paso 4: Configuración de resolución DNSLink sin desfase de caché
----------------------------------------------------------------
Los enrutadores residenciales y de campus suelen almacenar en caché los registros TXT de DNSLink por tiempos prolongados. Para que tu nodo resuelva los identificadores de contenido (CID) recién publicados sin esperar vencimientos de caché local, configura Kubo para consultar directamente el punto de resolución DoH de Cloudflare para el dominio ``mx-os.mx``:

.. code-block:: bash

   # Delegar resolución DNSLink de mx-os.mx a Cloudflare DoH (FQDN estricto)
   ipfs config --json DNS.Resolvers '{"mx-os.mx.": "https://cloudflare-dns.com/dns-query", ".": "auto"}'
   systemctl --user restart ipfs.service

Paso 5: Explora los módulos disponibles con ipfs ls
---------------------------------------------------
Antes de enclavillar, puedes consultar directamente la estructura y los módulos publicados en el catálogo maestro ejecutando ``ipfs ls``:

.. code-block:: bash

   # 1. Explorar la raíz completa del catálogo comunitario
   ipfs ls /ipns/mirrors.mx-os.mx

   # 2. Listar las ramas de Fedora disponibles (43, 44, 45)
   ipfs ls /ipns/mirrors.mx-os.mx/fedora/releases

   # 3. Listar medios de instalación ISO disponibles
   ipfs ls /ipns/mirrors.mx-os.mx/fedora/iso

   # 4. Listar los repositorios de CentOS Stream 10
   ipfs ls /ipns/mirrors.mx-os.mx/centos-stream/10-stream

   # 5. Listar los repositorios de Grupos de Interés Especial (SIGs) de CentOS Stream 10
   ipfs ls /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream

Paso 6: Elige y enclavilla tus módulos
--------------------------------------
No necesitas descargar los cientos de gigabytes del catálogo completo. Selecciona el módulo que mejor se adapte a tu cuota de almacenamiento en disco:

.. list-table::
   :header-rows: 1
   :widths: 28 42 15 15

   * - Módulo
     - Comando de Enclavillado
     - Tamaño en Red
     - Estimado Final
   * - **Imágenes ISO Fedora 43**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/43``
     - 1.2G
     - ~3.5 GB
   * - **Imágenes ISO Fedora 44**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/44``
     - 1.2G
     - ~3.5 GB
   * - **Imágenes ISO Fedora 45**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/45``
     - 1.2G
     - ~3.5 GB
   * - **Todas las Imágenes ISO (43, 44, 45)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso``
     - 3.5G
     - ~10 GB
   * - **CentOS 10 BaseOS**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/BaseOS``
     - 7.0G
     - ~15 GB
   * - **CentOS 10 AppStream**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/AppStream``
     - 29G
     - ~45 GB
   * - **CentOS 10 CRB (CodeReady Builder)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/CRB``
     - 31G
     - ~30 GB
   * - **CentOS 10 HighAvailability**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/HighAvailability``
     - 166M
     - ~500 MB
   * - **CentOS 10 NFV y RT (Redes y Tiempo Real)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/RT``
     - 2.1G
     - ~5.0 GB
   * - **CentOS 10 SIG Extras (extras-common)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/extras``
     - 948K
     - ~50 MB
   * - **CentOS 10 SIG Virtualización (KVM y oVirt)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/virt``
     - 1.4G
     - ~500 MB
   * - **CentOS 10 SIG Módulos de Kernel (kmods)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/kmods``
     - 192M
     - ~500 MB
   * - **CentOS 10 SIG Mensajería (RabbitMQ)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/messaging``
     - 572M
     - ~1.0 GB
   * - **CentOS 10 SIG Almacenamiento (Ceph, Samba, NFS Ganesha)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/storage``
     - 6.4G
     - ~6.0 GB
   * - **CentOS 10 SIG Hyperscale (Kernel y Paquetes Avanzados)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/hyperscale``
     - 9.8G
     - ~10 GB
   * - **CentOS 10 Stream Completo (Base + SIGs)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream``
     - 69G
     - ~105 GB
   * - **Paquetería Fedora 43 Everything**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/43/Everything``
     - 118G
     - ~125 GB
   * - **Paquetería Fedora 44 Everything**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/44/Everything``
     - 0
     - ~125 GB
   * - **Paquetería Fedora 45 Everything (Desarrollo)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/45/Everything``
     - 0
     - ~125 GB
   * - **Catálogo Canónico Completo**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx``
     - 195G
     - ~480 GB

Gestión Eficiente de Almacenamiento: Btrfs, CoW y Subvolúmenes
--------------------------------------------------------------
Para los operadores de nodos guardianes que sincronizan o almacenan paquetes localmente, la infraestructura de espejos de MxOS aprovecha las capacidades nativas de **Btrfs** y la copia en escritura (**CoW**; *Copy-on-Write*):

* **Eliminación atómica e instantánea de módulos enteros:** En lugar de ejecutar borrados recursivos ordinarios (``rm -rf``) que tardan minutos en recorrer y desvincular decenas de miles de archivos individuales sobrecargando la cola de entrada/salida (I/O), cada módulo del catálogo puede residir en un subvolumen Btrfs independiente. Borrar un repositorio completo de más de 100 GB se efectúa de forma instantánea a nivel de metadatos mediante ``btrfs subvolume delete``.
* **Instantáneas de respaldo con costo cero de almacenamiento:** Antes de sincronizar o aplicar depuraciones en un repositorio, es posible generar una instantánea de solo lectura del módulo en milisegundos (``btrfs subvolume snapshot -r``). La instantánea no consume espacio adicional en disco gracias a CoW; únicamente requiere almacenamiento nuevo conforme upstream añade o sobrescribe bloques.
* **Clonación y ramificación instantánea:** La duplicación de repositorios o la preparación de versiones de prueba se realiza con *reflinks* (``cp -a --reflink=always``), compartiendo los mismos bloques físicos de disco de forma transparente.
* **Permisos para operadores no privilegiados:** Al habilitar la opción de montaje ``user_subvol_rm_allowed`` en ``/etc/fstab`` para el punto de montaje de IPFS, los operadores pueden crear, tomar instantáneas y eliminar subvolúmenes de módulos sin necesidad de privilegios de superusuario (``root``).
* **Herramienta de gestión integrada:** El repositorio incluye la herramienta `bin/mxos-btrfs.bash`_ para automatizar estas operaciones:

  .. code-block:: bash

     # 1. Consultar estado de subvolúmenes e instantáneas por módulo
     ./bin/mxos-btrfs.bash list

     # 2. Inicializar o migrar módulos a subvolúmenes Btrfs
     ./bin/mxos-btrfs.bash init all

     # 3. Crear una instantánea de respaldo previa a sincronización
     ./bin/mxos-btrfs.bash snapshot centos-baseos pre-sync

     # 4. Eliminar un módulo entero de forma instantánea y atómica
     ./bin/mxos-btrfs.bash delete fedora-everything-43

     # 5. Restaurar un módulo a partir de una instantánea previa
     ./bin/mxos-btrfs.bash rollback centos-baseos centos-baseos-pre-sync

Para consultar procedimientos de dimensionamiento, políticas de recolección de basura (GC) y administración avanzada de almacenamiento, consulta la `Guía Completa para Operadores de Nodos Guardianes`_ en la documentación del repositorio.

.. _Guía Completa para Operadores de Nodos Guardianes: docs/guides/operador-nodo.rst
.. _bin/mxos-btrfs.bash: bin/mxos-btrfs.bash

Consumo del Espejo desde Clientes DNF
=====================================
Si además de enclavillar deseas actualizar tus equipos locales consumiendo paquetes desde la red comunitaria, configura DNF de la siguiente manera:

Opción recomendada: Conexión mediante nodo IPFS local
-----------------------------------------------------
Al contar con Kubo activo en tu equipo (escuchando en ``127.0.0.1:8080``), los paquetes se descargan por la red P2P. Si otro equipo en tu misma red local ya descargó una actualización, tu máquina la obtendrá a la velocidad de la red interna sin salir a internet.

Para Fedora 43, 44, 45 o Rawhide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Crea el archivo ``/etc/yum.repos.d/fedora-mxos-ipfs.repo`` con privilegios administrativos:

.. code-block:: ini

   [fedora-mxos-ipfs]
   name=Fedora $releasever - $basearch (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/fedora/releases/$releasever/Everything/$basearch/os/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch

   [fedora-updates-mxos-ipfs]
   name=Fedora $releasever Updates - $basearch (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/fedora/updates/$releasever/$basearch/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch

Para CentOS Stream 10
~~~~~~~~~~~~~~~~~~~~~
Crea el archivo ``/etc/yum.repos.d/centos-stream-mxos-ipfs.repo``:

.. code-block:: ini

   [cs10-baseos-mxos-ipfs]
   name=CentOS Stream 10 - BaseOS (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/10-stream/BaseOS/$basearch/os/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

   [cs10-appstream-mxos-ipfs]
   name=CentOS Stream 10 - AppStream (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/10-stream/AppStream/$basearch/os/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

   [cs10-crb-mxos-ipfs]
   name=CentOS Stream 10 - CRB (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/10-stream/CRB/$basearch/os/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

   [cs10-highavailability-mxos-ipfs]
   name=CentOS Stream 10 - HighAvailability (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/10-stream/HighAvailability/$basearch/os/
   enabled=0
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

   [cs10-rt-mxos-ipfs]
   name=CentOS Stream 10 - Real Time (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/10-stream/RT/$basearch/os/
   enabled=0
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

   [cs10-extras-mxos-ipfs]
   name=CentOS Stream 10 - Extras Comunes (Espejo MxOS IPFS)
   baseurl=http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/extras/$basearch/extras-common/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

Opción estándar: Conexión HTTPS directa
---------------------------------------
Si tu equipo no ejecuta un demonio IPFS, puedes configurar tus repositorios apuntando directamente al punto de entrada HTTPS:

.. code-block:: ini

   [fedora-mxos-https]
   name=Fedora $releasever - $basearch (MxOS HTTPS)
   baseurl=https://mirrors.mx-os.mx/fedora/releases/$releasever/Everything/$basearch/os/
   enabled=1
   metadata_expire=6h
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch

Estructura del Catálogo Canónico
================================
El árbol publicado bajo ``/ipns/mirrors.mx-os.mx`` respeta rigurosamente las convenciones de rutas de Fedora y CentOS Stream:

.. code-block:: text

   mirrors.mx-os.mx/
   ├── README.rst                     <- Documento de bienvenida e instrucciones
   ├── README.html                    <- Portal web estilizado con selector de temas
   ├── guardianes.json                <- Directorio comunitario de nodos custodios verificados
   ├── vigia/                         <- Tablero de telemetría y cartografía P2P
   │   ├── index.html                 <- Aplicación web autocontenida
   │   └── telemetry.json             <- Instantánea JSON de nodos guardianes
   ├── fedora/
   │   ├── iso/                       <- Imágenes de instalación de Fedora
   │   ├── releases/                  <- Árbol Everything por versión y arquitectura
   │   └── updates/                   <- Repositorios de actualizaciones continuas
   └── centos-stream/
       ├── iso/                       <- Medios de instalación de CentOS Stream
       ├── 10-stream/
       │   ├── BaseOS/                <- Paquetes base y núcleo del sistema
       │   ├── AppStream/             <- Módulos y aplicaciones adicionales
       │   ├── CRB/                   <- CodeReady Linux Builder
       │   ├── HighAvailability/     <- Paquetes para clústeres de alta disponibilidad
       │   ├── NFV/                   <- Virtualización de funciones de red
       │   └── RT/                    <- Núcleo y herramientas en tiempo real
       └── SIGs/
           └── 10-stream/
               └── extras/            <- Paquetería complementaria de SIGs (extras-common)

Identificación y Reconocimiento de Nodos Guardianes
===================================================
La participación en el enjambre de MxOS es voluntaria, descentralizada y respetuosa de la privacidad por diseño. No existe registro forzoso, telemetría intrusiva ni recopilación obligatoria de datos.

Custodia Anónima: Participación Plena y Soberana
------------------------------------------------
En la Red de Espejos Comunitarios de Fundación MxOS, **la custodia anónima es totalmente válida, bienvenida y considerada de primera clase**.

* **Sin registros ni trámites:** No necesitas registrarte, crear cuentas ni proporcionar nombres, correos ni datos personales.
* **Operación natural entre pares:** Al levantar tu demonio Kubo y enclavillar cualquier módulo, tu nodo intercambia paquetes y bloques de forma nativa a través de la DHT de libp2p y el protocolo Bitswap.
* **Identidad criptográfica pura:** En la red pública, tu nodo se anuncia únicamente mediante su ``PeerID`` criptográfico (por ejemplo, ``12D3KooWBVZfAQ...``), derivado de tu par de llaves Ed25519.
* **Mismo peso y soberanía:** Los bloques servidos por un guardián anónimo tienen exactamente la misma validez, velocidad y prioridad para la comunidad que los de un nodo registrado; fortalecen la resiliencia colectiva y alimentan a los clientes locales sin dejar registro de identidad civil.

Registro Voluntario de tu Nodo a tu Nombre
------------------------------------------
Si como operador individual, colectivo tecnológico, universidad, centro de cómputo o empresa privada **deseas vincular públicamente tu nodo a tu nombre, organización o proyecto**, puedes solicitar tu inclusión en el Directorio de Custodios.

Al registrarte, tu nodo aparecerá formalmente en el radar de `Vigía`_ con tus datos verificados:

* **Alias o distintivo:** Tu usuario o identificador comunitario; por ejemplo, ``@tu_usuario`` o ``udg-sistemas``.
* **Nombre completo o entidad:** Nombre civil o denominación institucional formal.
* **Afiliación u organización:** Colectivo, empresa o universidad que respalda el nodo; por ejemplo, ``EVALinux`` o ``HOBOPS.IO``.
* **Ubicación:** Ciudad, estado y país en texto canónico; por ejemplo, ``Ixtlahuacán de los Membrillos, Jalisco, México``; sin abreviaturas.
* **Sitio web:** Portal institucional o página personal verificada bajo HTTPS; por ejemplo, ``https://evalinux.com``.
* **Insignia honorífica:** Distintivo asignado en el tablero de Vigía; por ejemplo, Guardián Pionero, Espejo Académico o Gateway Oficial.

Procedimiento para Registrar tu Nodo a tu Nombre
------------------------------------------------
Para añadir tu nodo al archivo ``guardianes.json`` y figurar formalmente con tu identidad en el espejo comunitario, sigue estos pasos:

1. **Obtén el identificador PeerID de tu nodo:**

   .. code-block:: bash

      ipfs id -f="<id>\n"

2. **Asegúrate de estar compartiendo al menos un módulo o el catálogo:**

   .. code-block:: bash

      ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso

3. **Edita el archivo ``guardianes.json`` en tu copia del repositorio:**
   Agrega una entrada dentro del objeto ``"guardianes"`` utilizando tu PeerID como clave:

   .. code-block:: json

      "12D3KooWBVZfAQyPExhScDpiG4Hahh3e6QmwRZRVopib1ThgUo2g": {
        "alias": "renich",
        "nombre": "Rénich Bon Ćirić",
        "organizacion": "EVALinux",
        "ubicacion": "Ixtlahuacán de los Membrillos, Jalisco, México",
        "sitio": "https://evalinux.com",
        "contacto": "renich@evalinux.com",
        "rol": "guardian",
        "insignia": "🛡️ Guardián Pionero",
        "verificacion": "gitlab"
      }

4. **Reglas para el registro:**

   * Utiliza el nombre completo del estado (por ejemplo, ``Jalisco`` o ``Querétaro``; nunca abreviado).
   * Evita espacios alrededor de diagonales; utiliza redacción directa con comas o conjunciones.
   * Proporciona un enlace HTTPS funcional en el campo ``sitio``.

5. **Envía tu solicitud:**
   Crea una rama con tu cambio y abre un Merge Request en nuestro repositorio de Git (`git.mx-os.mx/MxOS/mirrors`_ o `gitlab.com/mxos/mirrors`_). Una vez aprobado, tu nodo aparecerá automáticamente vinculado en `vigia.mx-os.mx`_ y en el espejo comunitario.

Participación Anónima y Privacidad
----------------------------------
Fundación MxOS respeta plenamente tu derecho a la privacidad. **Se vale totalmente operar y enclavillar tu nodo de forma anónima**.

No es obligatorio registrar tu nodo en ``guardianes.json`` ni revelar tu identidad civil, alias o ubicación para colaborar con la red. Cualquier instancia de Kubo conectada al enjambre global que enclaville uno o más módulos mediante ``ipfs pin add /ipns/mirrors.mx-os.mx/...`` participa de forma inmediata y automática en el intercambio de bloques vía Bitswap. Tu nodo servirá datos a otros pares cercanos, deduplicará tráfico y acelerará las descargas en tu región con absoluta confidencialidad y sin dejar rastro de identidad en el catálogo.

El registro en ``guardianes.json`` es un reconocimiento honorífico y voluntario para aquellos operadores, instituciones o empresas que desean hacer pública su contribución en el observatorio de `Vigía`_ y en el portal web comunitario.

Seguridad e Integridad Criptográfica
====================================
La seguridad en la red de espejos descansa en dos barreras independientes e infranqueables:

1. **Integridad de bloques:** La naturaleza direccionada por contenido de IPFS garantiza que ningún bit pueda alterarse en tránsito; si un bloque difiere de su hash, el cliente lo descarta automáticamente.
2. **Firmas GPG oficiales:** El gestor DNF valida cada RPM contra la llave pública oficial del proyecto correspondiente (ubicada en ``/etc/pki/rpm-gpg/``). Ni los operadores de nodos ni atacantes intermedios pueden inyectar código no firmado.
3. **Identidad soberana Ed25519 (IPNS):** El catálogo se firma con la llave criptográfica dedicada ``mxos-mirrors`` (``k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v``), permitiendo la verificación independiente de DNS mediante la ruta ``/ipns/k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v``.

Herramientas y Automatización en este Repositorio
=================================================
Este repositorio contiene los scripts de gestión y automatización de la infraestructura:

* `bin/mxos-btrfs.bash`_: Gestión de subvolúmenes Btrfs, instantáneas CoW y borrado atómico de módulos.
* `bin/mxos-mirror-sync.bash`_: Sincronización diferencial upstream mediante rsync preservando metadatos.
* `bin/mxos-repo-sync.bash`_: Sincronización completa de paquetes con dnf5 reposync, bloqueo exclusivo de concurrencia e ingesta integral.
* `bin/mxos-tmux-sync.bash`_: Gestión de descargas y sincronizaciones persistentes en segundo plano con tmux.
* `bin/mxos-mirror-ingest.bash`_: Ingesta UnixFS en Kubo con soporte de filestore (``--nocopy``).
* `bin/mxos-ipns-publish.bash`_: Firma y publicación en IPNS con la llave Ed25519 del proyecto.
* `bin/mxos-key-backup.bash`_: Exportación, respaldo cifrado (age/gpg) y restauración de la llave Ed25519.
* `bin/mxos-dnslink-update.bash`_: Actualización desatendida del registro DNSLink en Cloudflare mediante API REST.
* `bin/mxos-mirror.bash`_: Orquestador integral del ciclo completo (sincronizar, ingerir, firmar, publicar y replicar).
* `vigia/`_: Colector de telemetría P2P en Crystal y tablero web de observabilidad (`repositorio en git.mx-os.mx`_).
* `etc/caddy/Caddyfile`_: Plantilla de proxy inverso para Caddy.
* `etc/nginx/mirrors.mx-os.mx.conf`_: Plantilla de configuración para Nginx.
* `systemd/`_: Unidades de servicio y temporizadores de systemd para sincronización cuatridiaria (00:00, 06:00, 12:00 y 18:00).

.. _bin/mxos-btrfs.bash: bin/mxos-btrfs.bash
.. _bin/mxos-mirror-sync.bash: bin/mxos-mirror-sync.bash
.. _bin/mxos-repo-sync.bash: bin/mxos-repo-sync.bash
.. _bin/mxos-tmux-sync.bash: bin/mxos-tmux-sync.bash
.. _bin/mxos-mirror-ingest.bash: bin/mxos-mirror-ingest.bash
.. _bin/mxos-ipns-publish.bash: bin/mxos-ipns-publish.bash
.. _bin/mxos-key-backup.bash: bin/mxos-key-backup.bash
.. _bin/mxos-dnslink-update.bash: bin/mxos-dnslink-update.bash
.. _bin/mxos-mirror.bash: bin/mxos-mirror.bash
.. _vigia/: vigia/
.. _vigia.mx-os.mx: https://mirrors.mx-os.mx/vigia/
.. _repositorio en git.mx-os.mx: https://git.mx-os.mx/MxOS/vigia
.. _git.mx-os.mx/MxOS/mirrors: https://git.mx-os.mx/MxOS/mirrors
.. _gitlab.com/mxos/mirrors: https://gitlab.com/mxos/mirrors
.. _etc/caddy/Caddyfile: etc/caddy/Caddyfile
.. _etc/nginx/mirrors.mx-os.mx.conf: etc/nginx/mirrors.mx-os.mx.conf
.. _systemd/: systemd/

Documentación Técnica Detallada
===============================
Para profundizar en las especificaciones y manuales, consulta el directorio `docs/`_:

* `docs/index.rst`_: Índice general de la documentación.
* `docs/business/spec.rst`_: Modelo estratégico, justificación e incentivos comunitarios.
* `docs/functional/spec.rst`_: Especificación de catálogo modular, pineo y telemetría pasiva.
* `docs/technical/spec.rst`_: Arquitectura de red, resolución DNSLink y puente MirrorManager.
* `docs/guides/index.rst`_: Manuales paso a paso para operadores, clientes y replicación autónoma.
* `docs/project/roadmap.rst`_: Fases de ejecución y seguimiento del proyecto.

.. _docs/: docs/
.. _docs/index.rst: docs/index.rst
.. _docs/business/spec.rst: docs/business/spec.rst
.. _docs/functional/spec.rst: docs/functional/spec.rst
.. _docs/technical/spec.rst: docs/technical/spec.rst
.. _docs/guides/index.rst: docs/guides/index.rst
.. _docs/project/roadmap.rst: docs/project/roadmap.rst

Canales de Comunidad y Contacto
===============================

* **Canal oficial de Telegram:** `@mx_os_mx`_
* **Sitio web:** `mx-os.mx`_
* **Repositorios de código:** `git.mx-os.mx`_

.. _@mx_os_mx: https://t.me/mx_os_mx
.. _mx-os.mx: https://mx-os.mx
.. _git.mx-os.mx: https://git.mx-os.mx
.. _Vigía: https://mirrors.mx-os.mx/vigia/

Licenciamiento
==============
Este proyecto opera bajo un modelo de licenciamiento libre y comunitario:

* **Documentación y especificaciones:** Licenciadas bajo `GNU Free Documentation License v1.3 o posterior`_ (GNU FDL v1.3+) sin secciones invariantes, sin textos de portada y sin textos de contraportada, en modelo dual con `Creative Commons Atribución-CompartirIgual 4.0 Internacional`_ (CC-BY-SA-4.0).
* **Herramientas, scripts y configuraciones:** Licenciadas bajo la `Licencia Pública General de GNU v3.0 o posterior`_ (GNU GPLv3+).

.. _GNU Free Documentation License v1.3 o posterior: https://www.gnu.org/licenses/fdl-1.3.html
.. _Creative Commons Atribución-CompartirIgual 4.0 Internacional: https://creativecommons.org/licenses/by-sa/4.0/
.. _Licencia Pública General de GNU v3.0 o posterior: https://www.gnu.org/licenses/gpl-3.0.html