ansible-koji/docs/instalación.rst

====================================
Procedimiento de Instalación de Koji
====================================

Este documento describe los pasos completos que necesitas para configurar un sistema de compilación Koji funcional, desde la
generación inicial de certificados hasta el arranque del entorno de compilación. Aquí consolidamos información de la documentación
de Koji y la experiencia práctica.

Fase 1: Autoridad de Certificación y Generación de Certificados SSL
===================================================================
Esta fase establece la base criptográfica para que los componentes de Koji se comuniquen de forma segura.

Crea la Autoridad de Certificación (CA):
   Crea un directorio dedicado para tu infraestructura PKI de Koji (p. ej., `/etc/pki/koji`).
   Genera un certificado de CA Raíz autofirmado y su clave privada correspondiente. Usarás esta CA para firmar todos los demás certificados de componentes de Koji.
Genera Certificados de Componentes y Usuarios:
   Para cada componente de Koji que requiere autenticación (koji_hub, koji-web, kojid, kojira, dist-git y usuarios administradores), genera
   una solicitud de firma de certificado (CSR) única y una clave privada.

   Certificados del Lado del Servidor (koji_hub, koji-web, dist-git):
      El Common Name (CN) en estos certificados *debe* coincidir con el
      Nombre de Dominio Completo (FQDN) del servidor donde los desplegarás. Estos certificados deben incluir `serverAuth` en su
      `extendedKeyUsage`.
   Certificados del Lado del Cliente (kojid, kojira, usuarios administradores):
      El CN para estos certificados debe coincidir con
      el nombre de usuario de Koji que usarás para la autenticación. Estos certificados deben incluir `clientAuth` en su
      `extendedKeyUsage`.

   Firma cada CSR con tu CA Raíz recién creada para generar los certificados de componente/usuario.
   Combina la clave privada de cada componente y su certificado firmado en un único archivo `.pem`. Los clientes de Koji usan a
   menudo este archivo `.pem`.
   Para que los usuarios administradores accedan a través del navegador web, genera un paquete PKCS12 (`.p12`) a partir del
   certificado y la clave del usuario, que incluya el certificado de la CA.
   
   **Nota de Seguridad**: Para la generación de claves GPG, utiliza archivos temporales seguros que se eliminen inmediatamente después de su uso para evitar exponer la frase de paso.

Fase 2: Configuración de la Base de Datos PostgreSQL
====================================================
Koji usa una base de datos PostgreSQL para almacenar todos los metadatos relacionados con la compilación, la información del usuario y la configuración.

Instala e Inicializa PostgreSQL:
   Instala el paquete `postgresql-server` en tu host de base de datos.
   Inicializa el clúster de la base de datos PostgreSQL.
Crea la Base de Datos y el Usuario de Koji:
   Como el usuario `postgres`, crea una base de datos dedicada para Koji (p. ej., `koji`).
   Crea un usuario de PostgreSQL dedicado (p. ej., `koji`) que Koji usará para conectarse a la base de datos. Asígnale una
   contraseña segura a este usuario.
Carga el Esquema de Koji:
   Carga el esquema de la base de datos de Koji desde el archivo SQL proporcionado (normalmente `/usr/share/koji/schema.sql` del
   paquete `koji`) en la base de datos de Koji que acabas de crear. Asegúrate de hacerlo como el usuario de la base de datos de
   Koji para mantener la propiedad correcta.
Configura el Acceso a la Base de Datos (`postgresql.conf` y `pg_hba.conf`):
   Edita `postgresql.conf` para:

   * Habilitar SSL (`ssl = on`).
   * Especificar los archivos de certificado y clave del servidor (`ssl_cert_file`, `ssl_key_file`).
   * Especificar el archivo del certificado de la CA (`ssl_ca_file`).
   * Configurar `listen_addresses` para permitir conexiones desde Koji Hub (p. ej., `'*'`).
   * Aumentar `max_connections` para satisfacer las necesidades de Koji (p. ej., `200`).

   Edita `pg_hba.conf` para permitir conexiones desde todos los hosts de Koji Hub (si hay varios) a la base de datos de Koji con SSL y un método de autenticación seguro (p. ej., `scram-sha-256`). Además, configura el acceso local para el usuario `postgres`.

Fase 3: Configuración de Koji Hub
=================================
El Koji Hub es el plano de control central para el sistema de compilación Koji.

Instala Koji Hub y Dependencias:
   Instala `koji_hub`, `koji-web`, `httpd`, `mod_ssl`, `mod_wsgi`, `python3-cryptography`, `nmap-ncat`, `postgresql` (bibliotecas
   de cliente), `policycoreutils-python-utils` y `python3-koji-hub-plugins`.
Configura el Hub (`/etc/koji_hub/hub.conf` y el directorio `.d`):
   Configura los parámetros de conexión de la base de datos (`DBName`, `DBUser`, `DBHost`, `DBPass`).
   Establece `KojiDir` en la ruta donde Koji almacenará los datos de compilación (p. ej., `/mnt/koji`).
   Configura los ajustes de autenticación, incluyendo `DNUsernameComponent` y `ProxyDNs` para la autenticación de certificados de
   cliente SSL.
   Asegúrate de que la configuración de plugins apunte a una ruta válida (p. ej., `/usr/lib/koji-hub-plugins`) y habilita los plugins necesarios (como `echo`).
Configura Apache para el Hub:
   Asegúrate de que `mod_ssl` y `mod_wsgi` estén habilitados.
   Edita `/etc/httpd/conf.d/ssl.conf` para que apunte al certificado del servidor, la clave y el certificado de la CA de Koji del
   Koji Hub.
   Configura el bloque `<Location /kojihub/ssllogin>` en `/etc/httpd/conf.d/kojihub.conf` para que requiera certificados de
   cliente SSL (`SSLVerifyClient require`).
Crea la Estructura del Sistema de Archivos de Koji:
   Crea los subdirectorios necesarios en `KojiDir` (p. ej., `packages`, `repos`, `work`, `scratch`, `repos-dist`, `certs`,
   `clients`).
   Asegúrate de que el usuario `apache` tenga la propiedad y los permisos de escritura adecuados en estos directorios.

Fase 4: Configuración de Koji Web
=================================
La interfaz Koji Web te proporciona una forma fácil de usar para interactuar con Koji.

Configura Koji Web (`/etc/kojiweb/web.conf` y el directorio `.d`):
   Establece `KojiHubURL` y `KojiFilesURL` en las URL apropiadas.
   Para la autenticación SSL, especifica `WebCert` (el archivo PEM del componente koji-web) y `KojiHubCA` (el certificado de la CA de Koji).
   Establece el valor de `Secret` en una contraseña segura y única.
Configura Apache para Koji Web:
   Configura el bloque `<Location /koji/login>` en `/etc/httpd/conf.d/kojiweb.conf` para que requiera certificados de cliente SSL si los usuarios se autenticarán a través de navegadores web.

Fase 5: Configuración de Dist-Git
=================================
El servidor Dist-Git (`cs10-koji-04.mx-os`) está configurado como un **Lookaside Cache** para gestionar los archivos fuente grandes (tarballs) necesarios para las compilaciones de Koji. **No aloja repositorios Git**; estos se gestionan externamente.

Instalación y Configuración:
   Instala `httpd` y `mod_ssl`.
   Configura `httpd` para servir el Lookaside Cache a través de HTTPS. El alias `/sources` apunta al directorio de caché (`/var/lib/dist-git/cache`).
   Asegúrate de que se fuerce el tráfico HTTPS mediante redirecciones y que **la navegación de directorios esté deshabilitada** para la coherencia con el comportamiento upstream de CentOS Stream.
Directorio y Permisos:
   Crea la estructura de directorios para la caché de fuentes (lookaside cache) en `/var/lib/dist-git/cache`.
   Asegura que los contextos de SELinux (`httpd_sys_content_t`) sean persistentes mediante `semanage fcontext`.

Fase 6: Configuración de Kojid (Constructor) y Kojira (Administrador de Repos)
==============================================================================

Configura Kojid (en cada host constructor):
   Instala `koji-builder`, `rpm-build`, `rpmdevtools` y `mock`.
   Edita `/etc/kojid/kojid.conf` para que apunte a la URL del servidor XML-RPC de Koji Hub.
   Especifica el certificado de cliente del componente `kojid` y el certificado de la CA de Koji.
   Establece el parámetro `user` en el FQDN del host constructor.
   Establece `topdir` en el directorio de Koji montado (p. ej., `/mnt/koji`).
   Establece `workdir` en un directorio local (p. ej., `/var/lib/kojid-work`).
   Configura `allowed_scms` para permitir la descarga de fuentes desde tu Dist-Git, utilizando un script wrapper (p. ej., `mxos-get-sources.bash`) para gestionar la caché de fuentes (lookaside cache).
   Asegúrate de que el servicio `kojid` se ejecute como `root` (predeterminado) y tenga los permisos adecuados en `workdir`.
   Agrega los usuarios que necesitan compilar paquetes (p. ej., `kojiadmin`) al grupo `mock`.

Configura Kojira (en el hub o en un host dedicado):
   Instala `koji-utils`.
   Edita `/etc/kojira/kojira.conf` para que apunte a la URL del servidor XML-RPC de Koji Hub.
   Especifica el certificado de cliente del componente `kojira` y el certificado de la CA de Koji.

Estos componentes manejan los procesos de compilación reales y la gestión de repositorios.

Fase 7: Configuración de SELinux y Firewall
===========================================
Un contexto de seguridad y un acceso a la red adecuados son cruciales para que Koji funcione.

Configuración de SELinux:
   Establece los siguientes booleanos de SELinux para permitir el acceso a la red y a los archivos necesarios para `httpd`:

   * `setsebool -P httpd_can_network_connect_db=1` (permite que httpd se conecte a PostgreSQL)
   * `setsebool -P httpd_can_network_connect=1` (permite que httpd realice conexiones de red generales)
   * `setsebool -P allow_httpd_anon_write=1` (permite que httpd escriba en áreas de contenido público)
   * `setsebool -P httpd_use_nfs=1` (si `/mnt/koji` está en un recurso compartido NFS)

   Aplica los contextos de archivo de SELinux correctos:

   * `semanage fcontext -a -t httpd_sys_rw_content_t "/mnt/koji(/.*)?"` (para contexto persistente en directorios de escritura)
   * `restorecon -r -v /mnt/koji` (para aplicar el contexto inmediatamente)
   
Configuración del Firewall:
   Abre los puertos de firewall necesarios en los hosts respectivos:

   * Koji Hub: HTTP (80/tcp), HTTPS (443/tcp).
   * Servidor PostgreSQL: PostgreSQL (5432/tcp) desde el Koji Hub.
   * Servidor NFS: NFS (servicios nfs, rpc-bind, mountd).
   * Dist-Git: HTTP (80/tcp), HTTPS (443/tcp).

Fase 8: Arranque del Entorno de Compilación de Koji
===================================================
Esta fase final prepara a Koji para que realice compilaciones reales.

Otorga Privilegios de Administrador al Usuario Inicial:
   Inserta manualmente un registro en la tabla `user_perms` en la base de datos de Koji para otorgarle al usuario administrador
   inicial (p. ej., `kojiadmin`) el permiso de `admin`. Este es un paso único para el administrador inicial.
Crea Etiquetas y un Destino de Compilación:
   Crea una etiqueta de destino (p. ej., `cs10`) donde terminarán los RPM finales: `koji add-tag cs10`.
   Crea una etiqueta de compilación (p. ej., `cs10-build`) que defina el contenido del buildroot y agrégale arquitecturas:
   `koji add-tag --parent cs10 --arches "x86_64" cs10-build`.
   Crea un destino de compilación que vincule la etiqueta de compilación y la etiqueta de destino:
   `koji add-target cs10-build cs10-build cs10`.
Puebla el Grupo de Compilación:
   Agrega los paquetes esenciales que se requieren para compilar (p. ej., `rpm-build`, `gcc`, `make`) al grupo `build` de tu
   etiqueta de compilación: `koji add-group-pkg cs10-build build <package_name>`.
   Alternativamente, importa definiciones de grupo desde una instancia de Koji existente (p. ej., el `comps.xml` de Fedora).
Regenera el Repositorio:
   Después de agregar paquetes al grupo de compilación, regenera el repositorio para la etiqueta de compilación: `koji regen-repo
   cs10-build`. Esto pone los paquetes a disposición de `kojid` para crear los buildroots.
Importa Paquetes Iniciales:
   Importa cualquier SRPM base y RPMs binarios a Koji y etiquétalos en tu etiqueta de destino. Esto proporciona una base de
   paquetes para la resolución de dependencias durante las compilaciones.

Este procedimiento detallado debería servirte como una guía completa para que configures un entorno Koji.

Fase 9: Características Adicionales
===================================

Recolección de Basura:
   Un servicio de systemd (`koji-cleanup.timer`) se ejecuta semanalmente para limpiar compilaciones antiguas
   y directorios de trabajo, ayudando a conservar el espacio en disco.
Notificaciones:
   Koji está configurado para registrar todos los eventos en `/var/log/koji_callbacks.log`. Este es un sistema
   de notificación básico que puede ser extendido para integrarse con otros sistemas.
Permisos Granulares:
   Se crea un usuario `builder` con permisos limitados. Este usuario solo puede realizar compilaciones,
   lo que mejora la seguridad al limitar el acceso a funciones administrativas.
Autoincremento de NVR:
   La etiqueta de compilación `mxos0-build` está configurada para incrementar automáticamente el número
   de release de los paquetes, simplificando el proceso de release.