feat: Integración de Siguldry PKCS#11 y spooler de firmas

* Implementación del rol de Ansible 'siguldry' para CentOS Stream 10
* Migración del plugin de firmas de Koji Hub a un spooler asíncrono
* Modificación de roles para utilizar empaquetamiento RPM nativo de siguldry-pkcs11
* Documentación de decisiones (ADRs) y roadmap en docs/technical/
* Limpieza de binarios locales pesados de PKCS#11 en Ansible

Co-developed-by: Gemini AI <renich+gemini@woralelandia.com>
Signed-off-by: Rénich Bon Ćirić <renich@woralelandia.com>

docs/technical/decisiones/2026-06-16-01-migracion_sigul_y_lookaside_centos.rst

@@ -0,0 +1,38 @@
+=============================================================
+Decisión de Diseño: Migración a Sigul Real y Lookaside CentOS
+=============================================================
+
+Este registro documenta la decisión de diseño de migrar a una infraestructura real de Sigul, estandarizar el lookaside cache para asemejarse a CentOS Stream, y posponer la autenticación basada en Kerberos en el entorno de staging.
+
+Contexto
+--------
+
+Para la distribución MxOS, es crucial emular la infraestructura de CentOS Stream 10 para garantizar compatibilidad, permitir la colaboración ascendente, y facilitar un entorno realista de aprendizaje. 
+
+Durante el desarrollo de la prueba de concepto (PoC) en staging:
+* Se implementó un emulador de firmas basado en una aplicación Flask simulada.
+* Se utilizó un script de descarga de fuentes personalizado en Mock que imita la estructura de CentOS Stream pero carece de integración oficial de herramientas de empaquetado.
+* Se consideró la integración de Kerberos (GSSAPI) para la autenticación en Koji. Sin embargo, no se dispone de un servidor FreeIPA inmediatamente y la máquina anfitrión de staging cuenta con recursos de hardware limitados que dificultan la ejecución de un nodo de identidad adicional.
+
+Decisión
+--------
+
+Se han tomado las siguientes decisiones de diseño:
+
+* **Migrar a Sigul Real**: Reemplazar el servidor Flask simulado por una implementación real de Sigul, compuesta por los demonios `sigul-server` (aislado) y `sigul-bridge` (intermediario), junto con el cliente `sigul` en lote.
+* **Estandarizar Lookaside Cache**: Alinear la estructura del lookaside cache y el script de obtención de fuentes con la herramienta estándar `get_sources.sh` y el formato oficial del archivo `sources` de CentOS Stream.
+* **Posponer Kerberos**: Mantener la autenticación en Koji mediante certificados SSL (TLS) en staging, y documentar el diseño de Kerberos/FreeIPA para implementaciones de producción de alta disponibilidad en el roadmap técnico.
+
+Justificación
+-------------
+
+* **Seguridad y Paridad**: El flujo de firmas real con Sigul previene que las llaves GPG de producción estén en contacto con Koji Hub o con Apache mod_wsgi, manteniendo las llaves seguras e igualando la arquitectura de producción de Red Hat/CentOS.
+* **Limitación de Recursos**: Prescindir de FreeIPA en staging permite que el entorno local se ejecute sin sobrecargar de memoria y procesamiento la máquina anfitrión, mientras se mantiene el foco en el flujo de compilación y empaquetado.
+* **Facilidad de Colaboración**: La estandarización de los metadatos Git y el lookaside cache asegura que los repositorios de paquetes de MxOS puedan interactuar limpiamente con otras instancias de Koji o herramientas de CentOS Stream.
+
+Consecuencias
+-------------
+
+* Se requiere configurar una PKI adicional para la comunicación segura entre el Hub, el puente y el servidor de Sigul.
+* Se deben actualizar los playbooks de Ansible para configurar Sigul y remover el servidor mock Flask.
+* La autenticación por certificados SSL (TLS) seguirá siendo el mecanismo principal para las conexiones de administración y compilación en staging.

docs/technical/decisiones/2026-06-16-02-bloqueo_python_nss_opciones_sigul.rst

@@ -0,0 +1,46 @@
+=============================================================
+Decisión de Diseño: Bloqueo de python-nss y Opciones de Firma
+=============================================================
+
+Este registro documenta el hallazgo técnico del bloqueo de compilación de ``python-nss`` en CentOS Stream 10 y evalúa las opciones de diseño para implementar la firma de paquetes RPM.
+
+Contexto
+--------
+
+Al intentar instalar el sistema de firmas oficial de CentOS Stream (Sigul legacy), encontramos que los paquetes de dependencias críticas ``python3-nss`` y ``python3-fedora`` no están disponibles en CentOS Stream 10 / EPEL 10. 
+
+Al intentar compilar ``python-nss`` directamente desde el código fuente de PyPI usando Python 3.12 y GCC 14 en el Hub VM, la compilación falló debido a un error de sintaxis C en el uso de la macro ``va_start`` en el archivo ``src/py_nspr_error.c``:
+
+.. code-block:: text
+
+   src/py_nspr_error.c:189:23: error: macro "va_start" requires 2 arguments, but only 1 given
+     189 |         va_start(vargs);
+         |                       ^
+
+Este error impide la instalación directa del cliente de firmas Sigul heredado en Python.
+
+Opciones de Diseño
+------------------
+
+Presentamos dos caminos de resolución para el entorno de staging:
+
+Opción A: Reconstruir Sigul Legacy (Homologación Estricta)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* **Descripción**: Descargar el código fuente de ``python-nss``, aplicar un parche en C para corregir el uso de la macro ``va_start`` (pasándole el último argumento nombrado del método), compilar el módulo de Python manualmente e instalar el SRPM de ``sigul`` heredado de EPEL 9 con la bandera ``--nodeps``.
+* **Pros**: Utiliza exactamente el mismo software, cliente CLI y flujo de firma que CentOS Stream usa actualmente.
+* **Contras**: Requiere mantener un parche manual en C para una dependencia heredada.
+
+Opción B: Adoptar Siguldry Moderno (Futuro de Fedora/CentOS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* **Descripción**: Configurar los servicios nativos de ``siguldry`` (que ya está disponible como paquete RPM en EPEL 10 por estar escrito en Rust). Dado que el cliente Rust no expone una llamada CLI directa de firma de archivos para PGP, se debe configurar el módulo PKCS#11 (``libsiguldry_pkcs11.so``) y enlazar ``rpmsign`` para que firme mediante este módulo de criptografía seguro.
+* **Pros**: Es nativo de CentOS Stream 10, no tiene dependencias de Python rotas, y es la arquitectura moderna elegida por el equipo de infraestructura de Fedora.
+* **Contras**: Requiere mayor complejidad de configuración criptográfica en el cliente (PKCS#11).
+
+Decisión de SCM (Git)
+---------------------
+
+Independientemente de la opción elegida para Sigul, se decide añadir restricciones estrictas de SCM en el archivo ``/etc/koji-hub/hub.conf`` para forzar que Koji únicamente acepte tareas de compilación provenientes del servidor Git local de MxOS:
+
+.. code-block:: ini
+
+   AllowedSCMs = git.mx-os.mx:/RPMs/*.git:*:use_common_checkout

docs/technical/decisiones/2026-06-16-03-implementacion_siguldry_pkcs11_spooler.rst

@@ -0,0 +1,29 @@
+========================================================
+Implementación de Siguldry PKCS#11 y Spooler de Firmas
+========================================================
+
+Este registro documenta la decisión e implementación de usar la compilación cruzada local del módulo PKCS#11 de Siguldry, su distribución e integración con el spooler de firmas de Koji.
+
+Contexto
+--------
+
+En el registro `2026-06-16-02` identificamos el bloqueo de compilación de ``python-nss`` en CentOS Stream 10, imposibilitando el cliente de Sigul tradicional. Seleccionamos Siguldry (Rust) como alternativa nativa moderna. 
+
+Sin embargo, al configurar el paquete RPM de ``siguldry`` en EPEL 10, encontramos que la biblioteca dinámica del módulo PKCS#11 (``libsiguldry_pkcs11.so``) no está empaquetada ni disponible en los repositorios de CentOS Stream 10 / EPEL 10, a pesar de que los servicios principales (server, bridge y client) sí están presentes.
+
+Decisión
+--------
+
+Para resolver la ausencia del módulo PKCS#11 y mantener la compatibilidad con el backend de firmas moderno de CentOS Stream 10, tomamos las siguientes decisiones:
+
+1. **Compilación en Host de Desarrollo**: Compilar localmente el sub-crate ``siguldry-pkcs11`` en la máquina de desarrollo del administrador (Fedora 43 x86_64) utilizando ``cargo build --release``.
+2. **Distribución vía Ansible**: Colocar la biblioteca compilada ``libsiguldry_pkcs11.so`` en los archivos del rol ``koji_hub`` y desplegarla en ``/usr/lib64/libsiguldry_pkcs11.so`` del Hub VM con permisos de ejecución.
+3. **Migración del Spooler a rpmsign**: Reescribir el demonio ``koji-sign-spooler`` para invocar el comando nativo ``rpmsign`` con el backend de Sequoia PGP (motor por defecto en EL10), configurando las variables de entorno ``PKCS11_MODULE_PATH`` y ``SIGULDRY_SOCKET`` en el proceso.
+4. **Almacenamiento de Credenciales con systemd**: Utilizar el directorio nativo ``/etc/credstore/`` para alojar las claves TLS y la frase de paso de GPG, permitiendo que systemd las exponga al demonio a través del mecanismo seguro de credenciales ``ImportCredential=siguldry.*``.
+
+Implicaciones
+-------------
+
+* **Seguridad Mejorada**: Las claves GPG y TLS se gestionan e importan usando los mecanismos de aislamiento modernos de systemd, sin exponer credenciales en archivos planos del sistema.
+* **Integración Transparente**: Al firmar los paquetes RPM en caliente mediante ``rpmsign`` sobre el almacenamiento NFS de Koji, extraemos la firma directamente usando ``koji.rip_rpm_sighdr`` para guardarla en la base de datos de Koji, igualando el comportamiento del Hub oficial.
+* **Independencia de Compilación en VMs**: Las máquinas virtuales de staging de Koji no requieren instalar herramientas de desarrollo pesadas como ``cargo`` o ``rustc``, manteniendo una huella de memoria ligera.

docs/technical/decisiones/2026-06-16-04-empaquetamiento_y_git_flujo_siguldry.rst

@@ -0,0 +1,46 @@
+====================================================================
+ADR 2026-06-16-04: Empaquetamiento y Flujo de Git para rust-siguldry
+====================================================================
+
+Estatus
+-------
+
+Propuesto
+
+Contexto
+--------
+
+La suite ``siguldry`` es crítica para implementar la firma de paquetes RPM en MxOS utilizando la integración de PKCS#11 con el spooler de firmas. Dado que el paquete upstream de EPEL 10 no incluye el módulo PKCS#11 (debido a limitaciones de las plantillas base de rust2rpm), necesitamos crear y mantener una versión modificada del paquete RPM que contenga el subpaquete ``siguldry-pkcs11`` (con la biblioteca ``libsiguldry_pkcs11.so``).
+
+Necesitamos definir:
+1. Dónde hospedar este repositorio en nuestra infraestructura de Git (Gitea/Forgejo en ``git.mx-os.mx``).
+2. Cómo interactuará esta versión con el sistema automatizado de sincronización ``rpms-sync``.
+3. Cuál será la estrategia para reducir la deuda técnica a largo plazo y colaborar con upstream.
+
+Decisión
+--------
+
+Adoptaremos las siguientes decisiones de diseño y organización:
+
+1. **Ubicación en Forgejo**:
+   Hospedaremos el repositorio en ``git.mx-os.mx/RPMs/rust-siguldry``. Esto mantiene el paquete clasificado junto a todos los demás RPMs de la distribución.
+
+2. **Estrategia de Ramas para rpms-sync**:
+   Seguiremos estrictamente la convención documentada en el flujo de trabajo de ``rpms-sync``:
+   * La rama ``c10s`` será un espejo limpio de sólo lectura del upstream de EPEL 10 y será gestionada exclusivamente por ``rpms-sync``.
+   * Crearemos la rama de distribución ``c10s-mxos`` a partir de ``c10s``. En esta rama aplicaremos nuestros parches al spec file (para definir el subpaquete ``siguldry-pkcs11`` y su instalación).
+   * De esta forma, las actualizaciones automatizadas de upstream se integrarán limpiamente vía merges periódicos de ``c10s`` a ``c10s-mxos`` por parte de los mantenedores, previniendo sobreescrituras accidentales.
+
+3. **Propuesta de Contribución a Upstream**:
+   Presentaremos el spec modificado al mantenedor oficial del paquete en Fedora/EPEL (en ``src.fedoraproject.org/rpms/rust-siguldry``). Dado que el módulo PKCS#11 es una funcionalidad estándar y esperada de Siguldry para la firma de RPMs, es altamente probable que sea aceptado upstream. Una vez fusionado, podremos prescindir de la rama de distribución local ``c10s-mxos`` y consumir el paquete directamente de EPEL 10.
+
+Consecuencias
+-------------
+
+* **Positivas**:
+  * Integración perfecta con el ciclo de vida y herramientas de MxOS (como ``rpms-sync``).
+  * Reducción de la deuda técnica al planear y ejecutar la contribución directa a EPEL 10.
+  * Mayor facilidad en el mantenimiento de actualizaciones de seguridad del paquete.
+
+* **Negativas / Desafíos**:
+  * Requiere un esfuerzo inicial de comunicación con los mantenedores de Fedora/EPEL y seguir sus lineamientos de empaquetamiento.

docs/technical/reference/siguldry_pkcs11.rst

@@ -0,0 +1,106 @@
+============================
+Siguldry PKCS#11 Integration
+============================
+
+Context and Overview
+--------------------
+
+Siguldry is a Rust-based, modern replacement for the legacy Sigul software signing service, designed to manage and isolate cryptographic keys. In CentOS Stream 10 (EL10) / EPEL 10 environments, the legacy python-based Sigul client is blocked due to compilation issues with the ``python-nss`` dependency. Siguldry resolves this by utilizing a modern Rust architecture, providing a PKCS#11 dynamic module (``libsiguldry_pkcs11.so``) to integrate with client-side signing utilities like ``rpmsign`` and Sequoia PGP.
+
+This document outlines the architecture, configuration files, systemd credentials, and RPM macro configurations required to sign RPM packages using keys held securely on a Siguldry server.
+
+Siguldry Architecture and Components
+------------------------------------
+
+The Siguldry architecture separates components into three distinct services:
+
+*   **Siguldry Server**: The secure backend node housing GPG signing keys (encrypted at rest). It does not listen on any network interfaces directly; instead, it establishes outgoing TLS connections to the bridge.
+*   **Siguldry Bridge**: The intermediary daemon acting as a secure proxy. It manages mutual TLS (mTLS) authenticated connections from both the server and client components, ferrying traffic between them.
+*   **Siguldry Client**: The client application (or its PKCS#11 module) that requests signatures from the bridge. The PKCS#11 module (``libsiguldry_pkcs11.so``) allows PKCS#11-compatible tools to leverage keys on the server.
+
+Configuration Files
+-------------------
+
+Client-side signing setups require configuration of the connection settings and authentication backends:
+
+1.  **Client Configuration (``/etc/siguldry/client.toml``)**
+    Defines the connection parameters to reach the Siguldry Bridge, including:
+    *   The host and port of the bridge.
+    *   Paths to the client TLS certificate, private key, and the CA certificate used for mTLS authentication.
+    *   The default key name to be used for signing requests.
+
+2.  **GnuPG Smartcard Daemon Override (``~/.gnupg/gpg-agent.conf``)**
+    If using the GnuPG backend for signing, the agent must load ``gnupg-pkcs11-scd`` instead of the standard ``scdaemon``:
+    
+    .. code-block:: text
+
+        scdaemon-program /usr/bin/gnupg-pkcs11-scd
+
+3.  **GnuPG PKCS#11 Daemon Configuration (``~/.gnupg/gnupg-pkcs11-scd.conf``)**
+    Defines the PKCS#11 provider details to load the Siguldry module:
+    
+    .. code-block:: text
+
+        providers siguldry
+        provider-siguldry-library /usr/lib64/libsiguldry_pkcs11.so
+
+Environment Variables and Credentials
+-------------------------------------
+
+Siguldry leverages the modern systemd credentials mechanism to securely pass sensitive configuration files and passphrases into its services at runtime.
+
+*   **``CREDENTIALS_DIRECTORY``**
+    An environment variable pointing to the system-managed directory containing decrypted credentials. In manual testing or non-systemd wrappers, this environment variable can be set manually.
+    
+*   **Decrypted Credentials Files**
+    Under the credentials directory, the following file targets are read by Siguldry:
+    *   ``sigul-client-config``: Contains the TOML configuration payload matching client connection configurations.
+    *   ``sigul-signing-key-passphrase``: Contains the plaintext passphrase used to unlock the GPG keys stored on the server.
+
+*   **PKCS#11 Module Environment Variables**
+    When using Sequoia PGP or related wrappers, specify the location of the PKCS#11 driver:
+    *   **``PKCS11_MODULE_PATH``**
+        Standard environment variable pointing to the module.
+    *   **``SQ_PKCS11_MODULE``**
+        Sequoia-specific fallback module path variable.
+    
+    *Example:*
+    
+    .. code-block:: bash
+
+        export PKCS11_MODULE_PATH=/usr/lib64/libsiguldry_pkcs11.so
+
+RPM Macro Configuration for rpmsign
+-----------------------------------
+
+RPM signing backends have transitioned to be implementation-agnostic in modern RPM versions (6.0+). The legacy `%__gpg_sign_cmd` macro is deprecated and ignored. Instead, implementation-independent macros must be used.
+
+Sequoia PGP Backend (EL10 Default)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CentOS Stream 10 uses Sequoia PGP (via ``rpm-sequoia``) as the default OpenPGP engine. Configure the signing macros in ``~/.config/rpm/macros``:
+
+.. code-block:: text
+
+    %_openpgp_sign sq
+    %_openpgp_sign_id <YOUR_KEY_FINGERPRINT>
+
+When running ``rpmsign --addsign``, the Sequoia engine interacts with the keystore daemon (``sequoia-keystore-server``) which accesses the Siguldry PKCS#11 module loaded via ``PKCS11_MODULE_PATH``.
+
+GnuPG Backend with gnupg-pkcs11-scd
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To explicitly enforce the traditional GnuPG engine, configure ``~/.config/rpm/macros``:
+
+.. code-block:: text
+
+    %_openpgp_sign gpg
+    %_openpgp_sign_id <YOUR_GPG_KEY_ID>
+
+Ensure the ``%__gpg`` macro resolves to the GnuPG binary:
+
+.. code-block:: text
+
+    %__gpg /usr/bin/gpg
+
+During execution, ``gpg-agent`` will delegate token operations to ``gnupg-pkcs11-scd``, which will sign using ``libsiguldry_pkcs11.so``.

docs/technical/reference/svg_conversion.rst

@@ -0,0 +1,105 @@
+==================================
+SVG to PNG Conversion on EL10/CS10
+==================================
+
+Context and Tooling Selection
+-----------------------------
+
+Personalizing Koji Web branding for MxOS requires converting corporate vector assets (specifically ``mxos.svg`` and ``mxos-reducido.svg``) into high-resolution PNG format (e.g. to be placed in ``images/koji.png`` within the custom theme). 
+
+Because enterprise servers require lightweight and reliable packages, CentOS Stream 10 (EL10) / RHEL 10 AppStream repositories provide native utilities for graphic conversion. Additional modern utilities can be pulled from EPEL 10 or installed via the Python ecosystem.
+
+Conversion Tools and Usage
+--------------------------
+
+Three primary methods are available on CentOS Stream 10 to perform SVG to PNG conversion:
+
+rsvg-convert (librsvg2-tools)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the recommended, native tool for server environments. It is extremely lightweight, fast, and does not require a graphical display server (X11/Wayland).
+
+*   **Package installation**:
+    
+    .. code-block:: bash
+
+        sudo dnf install librsvg2-tools
+
+*   **Command usage**:
+    To perform a simple conversion, use the output flag (``-o``):
+    
+    .. code-block:: bash
+
+        rsvg-convert -o koji.png mxos.svg
+
+*   **Sizing and aspect ratio preservation**:
+    Specify target dimensions directly. Use the ``--keep-aspect-ratio`` flag to prevent stretching:
+    
+    .. code-block:: bash
+
+        rsvg-convert -w 250 --keep-aspect-ratio -o koji.png mxos.svg
+
+Inkscape CLI
+~~~~~~~~~~~~
+
+Inkscape is a powerful editor, but is heavier than ``rsvg-convert``. It is useful if complex SVG features (like certain embedded filters or text styling) do not render correctly in ``rsvg-convert``.
+
+*   **Package installation**:
+    Depending on EPEL 10 availability, install via DNF or use Flatpak as an isolated container:
+    
+    .. code-block:: bash
+
+        sudo dnf install inkscape
+
+*   **Command usage**:
+    The modern Inkscape command-line structure uses the ``-o`` flag:
+    
+    .. code-block:: bash
+
+        inkscape -o koji.png mxos.svg
+
+*   **Sizing**:
+    Resize the export using the ``-w`` (width) or ``-h`` (height) options:
+    
+    .. code-block:: bash
+
+        inkscape -w 250 -o koji.png mxos.svg
+
+CairoSVG (Python Library)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CairoSVG is a Python-based SVG-to-PDF/PNG converter. It is not packaged as a native RPM in base EL10 repositories, but is useful for scripted configurations.
+
+*   **Installation**:
+    Install using Python's package manager within a virtual environment or on the user-level path:
+    
+    .. code-block:: bash
+
+        pip3 install --user cairosvg
+
+*   **Command usage**:
+    
+    .. code-block:: bash
+
+        cairosvg mxos.svg -o koji.png
+
+*   **Python Code integration**:
+    
+    .. code-block:: python
+
+        import cairosvg
+        cairosvg.svg2png(url='mxos.svg', write_to='koji.png', output_width=250)
+
+Application for Koji Web Branding
+---------------------------------
+
+To personalize the Koji Web theme for MxOS:
+
+1.  Convert the logo vector to the required logo size (standard Koji logos are usually around 100-250px wide):
+    
+    .. code-block:: bash
+
+        rsvg-convert -w 250 --keep-aspect-ratio -o koji.png mxos.svg
+        rsvg-convert -w 64 --keep-aspect-ratio -o koji-reducido.png mxos-reducido.svg
+
+2.  Copy the resulting PNG assets into the custom Koji Web static theme directory (e.g. ``/usr/share/koji-web/static/themes/mxos/images/koji.png``).

docs/technical/roadmap.rst

@@ -0,0 +1,48 @@
+==================================
+Roadmap de Desarrollo de MxOS Koji
+==================================
+
+Este roadmap define el camino a seguir para el desarrollo y optimización de la infraestructura de compilación de MxOS. El enfoque prioritario es lograr la compatibilidad absoluta con CentOS Stream 10 antes de introducir optimizaciones adicionales.
+
+Igualacion a CentOS Stream
+--------------------------
+
+El primer hito es replicar los mecanismos de compilación y firma oficiales para ser compatibles con CentOS Stream:
+
+* **Estandarización de Fuentes (Lookaside Cache)**:
+  * Adoptar el script oficial `get_sources.sh` o su equivalente compatible con el formato de la caché lookaside.
+  * Modificar los scripts de sincronización locales para integrarse con la estructura oficial.
+* **Firma con Sigul Oficial**:
+  * Desplegar en staging el servidor y el puente de Sigul (`sigul-server` y `sigul-bridge`) usando certificados TLS dedicados y políticas de ACL de Sigul.
+  * Configurar e importar llaves GPG reales de pruebas en el servidor de Sigul.
+  * Reescribir el plugin de Koji Hub (`sigul_sign.py`) para invocar el cliente `sigul` oficial.
+* **Políticas de SCM en el Hub**:
+  * Restringir el Koji Hub mediante la propiedad `AllowedSCMs` para forzar las compilaciones a partir de los repositorios Git en `git.mx-os.mx/RPMs/`.
+
+Branding de Koji a MxOS
+-----------------------
+
+Para personalizar la interfaz de Koji Web con la identidad gráfica de MxOS (utilizando los recursos de logotipos en SVG en la raíz del proyecto):
+
+* **Conversión de Recursos Gráficos**:
+  * Utilizar herramientas nativas de CentOS Stream 10 para convertir los archivos de logotipos SVG (``mxos.svg`` y ``mxos-reducido.svg``) a formato PNG con la resolución adecuada para Koji Web.
+* **Creación de Tema para Koji Web**:
+  * Implementar el rol de Ansible para crear el directorio del tema en `/usr/share/koji-web/static/themes/mxos/`.
+  * Copiar el logotipo de MxOS en `images/koji.png` dentro del tema.
+  * Personalizar la hoja de estilos `koji.css` del tema mxos para aplicar la paleta de colores y estilos corporativos.
+* **Configuración del Tema en el Servidor**:
+  * Configurar `KojiTheme = mxos` y `SiteName = MxOS Koji` en `/etc/kojiweb/web.conf` a través de las plantillas del rol `koji_hub`.
+
+Planes de Mejora y Escalabilidad
+--------------------------------
+
+Una vez alcanzada la paridad técnica con CentOS Stream, se procederá con las siguientes mejoras de infraestructura y automatización:
+
+* **Asincronía vía Bus de Mensajes**:
+  * Reemplazar los callbacks locales por la emisión de mensajes AMQP mediante `koji-messagebus` (RabbitMQ).
+  * Crear un servicio consumidor de firmas autónomo que escuche los eventos de compilación terminada para firmar paquetes asíncronamente sin afectar a Apache.
+* **Autenticación Centralizada (Kerberos)**:
+  * Integrar FreeIPA o Red Hat IDM para autenticar de manera segura a los builders y desarrolladores.
+  * Configurar `sssd` en los nodos y configurar `mod_auth_gssapi` en Koji Hub y Koji Web.
+* **Múltiples Builders**:
+  * Escalar horizontalmente el número de Koji Builders activos, asociándolos a canales especializados (como compilar arquitecturas secundarias o tareas prioritarias).

docs/technical/spec.rst

@@ -0,0 +1,43 @@
+===================================
+Especificación Técnica de MxOS Koji
+===================================
+
+Este documento detalla las especificaciones técnicas y requisitos de diseño del cluster de compilación de MxOS. El objetivo es mantener una compatibilidad estricta con la infraestructura de CentOS Stream 10 para facilitar la colaboración e integración de paquetes.
+
+Arquitectura y Componentes
+--------------------------
+
+El entorno está compuesto por 5 roles principales distribuidos en nodos independientes ejecutados bajo CentOS Stream 10:
+
+* **Koji Hub**: Servidor web Apache con mod_wsgi expuesto por HTTPS. Recibe las llamadas XML-RPC del cliente y los constructores, y maneja el estado de la base de datos.
+* **Koji DB**: Motor relacional PostgreSQL que almacena los metadatos de las tareas, paquetes, tags y firmas.
+* **Koji NFS**: Almacenamiento compartido montado en `/mnt/koji` en los nodos pertinentes para el almacenamiento de los RPMs y repositorios.
+* **Koji Builder**: Nodo ejecutor del demonio `kojid`. Inicia entornos aislados chroot de Mock para compilar los RPMs.
+* **Lookaside Cache (Dist-Git)**: Servidor web Apache con scripts CGI para la descarga de tarballs y fuentes externas.
+
+Integración con Git y Lookaside Cache
+-------------------------------------
+
+Para asegurar compatibilidad con CentOS Stream, los paquetes RPM se estructuran de la siguiente manera:
+
+* **Repositorios Git**: Hospedados bajo la organización `RPMs` en `git.mx-os.mx/RPMs/<paquete>.git`.
+* **Filtro de SCM (AllowedSCMs)**: El archivo `/etc/koji-hub/hub.conf` restringe las compilaciones a repositorios oficiales:
+  
+  .. code-block:: ini
+
+     AllowedSCMs = git.mx-os.mx:/RPMs/*.git:*:use_common_checkout
+
+* **Archivo sources**: Cada repositorio Git contiene un archivo `sources` en la raíz del proyecto. El formato del archivo es:
+  
+  .. code-block:: text
+
+     SHA512 (tarball.tar.gz) = hash_sha512_completo
+
+Firma de Paquetes con Sigul
+---------------------------
+
+La firma de los paquetes resultantes se realiza de manera segura y aislada usando la arquitectura oficial de Sigul:
+
+* **Sigul Server**: Nodo aislado donde reside el llavero GPG con la llave privada.
+* **Sigul Bridge**: Nodo intermediario en una zona de red restringida que recibe solicitudes del cliente y las despacha al servidor.
+* **Sigul Client**: Cliente CLI (`sigul`) instalado en el Koji Hub. Ejecuta solicitudes de firma mediante llamadas autenticadas por certificados SSL TLS y ACLs.