refs #2267 2682 2680 adds oglive and ogrepository documentation

i18n-docu/docs/es/administration/oglive.md

@@ -0,0 +1,118 @@
+# ogLive
+
+**ogLive** es el sistema operativo ligero que se ejecuta temporalmente en los clientes gestionados por OpenGnsys. Se encarga de ejecutar las órdenes enviadas desde la consola web, como la creación de imágenes, el despliegue de sistemas operativos o la ejecución de comandos remotos.
+
+ogLive está basado en Linux y se distribuye en formato ISO. Su gestión completa (descarga, instalación, selección por defecto, cacheado, etc.) se realiza desde el componente **ogboot**, por lo que en esta sección nos centraremos únicamente en el comportamiento de ogLive una vez que ha arrancado en el cliente.
+
+---
+
+## ¿Qué ocurre al arrancar ogLive?
+
+Cuando un cliente se inicia en modo PXE, se le envía:
+
+- El núcleo (`ogvmlinuz`) con los parámetros de arranque necesarios obtenidos desde la plantilla PXE asignada
+- El initrd (`oginitrd.img`)
+
+Estos archivos son montados en memoria, iniciando un entorno de Linux desde el que se puede interactuar con la consola web de OpenGnsys.
+
+> **Nota:**  
+> La máquina cliente debe tener al menos 1.5 GB de RAM para que ogLive funcione correctamente.
+
+Una vez operativo, el cliente carga y renderiza automáticamente una interfaz gráfica accesible por web (**ogBrowser**), que permite visualizar el estado del sistema, ver las particiones detectadas y recibir comandos directamente desde el servidor central.
+
+---
+
+## Interfaz del cliente ogLive
+
+La interfaz gráfica que se presenta tras el arranque muestra las particiones del sistema, indicando:
+
+- **Número de disco y partición**
+- **Tamaño de la partición**
+- **Tipo de sistema de archivos** (FAT32, NTFS, EXT4, CACHE, etc.)
+- **Sistema operativo detectado**, si lo hay
+- **Acciones disponibles**, como arrancar un sistema instalado
+
+Además, ofrece botones para reiniciar o apagar el cliente, así como un terminal inferior (modo técnico) para interacción directa.
+
+---
+
+## Asignación del menú ogLive
+
+El contenido de la interfaz web que se muestra al arrancar ogLive puede personalizarse desde la consola web de OpenGnsys. Para ello:
+
+1. Accede a la sección **Clientes** y edita el cliente deseado.
+2. En el formulario de edición, localiza el campo **Menú**.
+3. Selecciona uno de los menús disponibles.
+4. Guarda los cambios.
+
+Este menú determina qué archivos HTML o interfaces se cargan en el navegador del cliente cuando se ejecuta ogLive.
+
+---
+
+## Arquitectura y dependencias
+
+El correcto funcionamiento de ogLive requiere:
+
+- Haber configurado previamente un ogLive válido desde **ogboot**
+- Que el cliente tenga acceso a los archivos de arranque por **TFTP/HTTP**
+- Que el navegador embebido (**ogBrowser**) se comunique correctamente con el servidor web de OpenGnsys
+
+El sistema utiliza **Qt6** sobre **Sway** como entorno gráfico, y se ejecuta en memoria para evitar alteraciones en el disco del cliente.
+
+---
+
+## Notas adicionales
+
+- Se recomienda que el ogLive cargado por defecto esté cacheado en el cliente si se van a realizar operaciones intensivas, para reducir tráfico de red.
+- El arranque de ogLive puede automatizarse mediante plantillas PXE personalizadas.
+- Si el menú seleccionado en el cliente apunta a una URL no válida o inaccesible, la interfaz gráfica no se mostrará correctamente.
+
+---
+
+## Gestión de menús de inicio personalizados
+
+OpenGnsys permite definir menús personalizados que serán renderizados en el cliente al arrancar mediante el navegador embebido ogbrowser. Estos menús se utilizan como interfaz de instalación para el usuario, ofreciendo opciones como "Instalar Windows", "Instalar GNU/Linux" o "Apagar el equipo". La personalización de estos menús permite adaptar la experiencia de arranque a distintos grupos de ordenadores, aulas, o necesidades específicas de despliegue.
+
+Cada menú creado dispone de una URL pública única, la cual será asignada a los clientes desde la interfaz de administración. Esta URL es accedida automáticamente por ogbrowser tras el arranque del sistema ogLive.
+
+
+### Crear un nuevo menú
+
+Para dar de alta un nuevo menú personalizado, accede al módulo lateral **Menús** y pulsa sobre el botón **Añadir menú** situado en la parte superior derecha. Se abrirá un formulario como se muestra en la imagen:
+
+![oggui-oglive-menu-add.png](oggui-oglive-menu-add.png)
+
+**Los campos requeridos son:**
+
+- **Nombre del menú:** identificador único que se usará tanto en la lista de menús como en la URL pública.
+- **Resolución:** resolución base del menú para su diseño. Debe coincidir con la resolución del cliente o de la mayoría de los equipos destino (por ejemplo, 1920x1080).
+- **Comentarios (opcional):** anotaciones internas sobre el propósito del menú.
+- **Menú por defecto:** si se marca esta casilla, el menú quedará asignado como predeterminado para todos los clientes que no tengan uno asignado explícitamente.
+
+Una vez completado el formulario, pulsa en **Guardar**. El menú quedará registrado y aparecerá en la tabla principal de menús.
+
+---
+
+### Consultar y editar un menú existente
+
+En la tabla de menús creados, puedes ver información relevante de cada menú:
+
+- **Nombre del menú**
+- **URL pública:** dirección web completa a la que apuntará ogbrowser al arrancar (por ejemplo, `https://127.0.0.1:8443/menu/main`)
+- **Estado por defecto:** si es el menú predeterminado
+- **Resolución**
+- **Fecha de creación**
+- **Acciones disponibles:** editar o eliminar
+
+Al pulsar sobre el botón de edición, se accede a un panel que muestra una vista previa en tiempo real del menú renderizado. Este renderizado es el que se presentará en el cliente a través del navegador ogbrowser.
+
+![oggui-oglive-menu.png](oggui-oglive-menu.png)
+
+En esta vista puedes:
+
+- Modificar el nombre, resolución y comentarios del menú.
+- Visualizar en tiempo real el resultado HTML del menú.
+- Marcarlo como predeterminado.
+- Guardar los cambios realizados.
+
+![oggui-oglive-menu-edit.png](oggui-oglive-menu-edit.png)

i18n-docu/docs/es/administration/ogrepository.md

@@ -1,55 +1,212 @@
-# ogrepository
+## Introducción a ogRepository
 
-El componente OgRepository de OpenGnsys es el encargado de almacenar, organizar y distribuir las imágenes de sistema que serán desplegadas en los equipos cliente. Estas imágenes representan un estado completo del sistema operativo, las configuraciones y las aplicaciones instaladas en un equipo de referencia, y permiten clonar ese entorno a múltiples máquinas de forma automatizada y controlada.
+El componente **ogRepository** de OpenGnsys es el encargado de almacenar, gestionar y distribuir imágenes del sistema operativo utilizadas en los procesos de clonación. Estas imágenes permiten capturar el estado completo de un sistema y restaurarlo posteriormente en otros equipos, ya sea de forma individual o masiva.
 
-OgRepository actúa como un repositorio central o distribuido, permitiendo a los administradores mantener una colección organizada de imágenes y controlar su disponibilidad, distribución y verificación.
+A través de la consola web de administración, ogRepository ofrece una interfaz clara y centralizada desde la que es posible visualizar, importar, exportar, verificar la integridad y eliminar imágenes almacenadas en el sistema. También se encarga de generar los ficheros auxiliares necesarios para cada imagen, como sumas de verificación, ficheros de tamaño, metainformación y archivos `.torrent`, imprescindibles para ciertos métodos de transmisión como P2P.
 
-El módulo ogrepository ofrece una interfaz web dentro de OpenGnsys para realizar las siguientes acciones:
+### Tipos de imágenes compatibles
 
-- Crear imágenes monolíticas de un sistema operativo a partir de un cliente previamente arrancado con ogLive.
+- **Imágenes monolíticas:**  
+    Capturas completas de una partición, almacenadas en un único fichero comprimido con el algoritmo Zstandard (`.img`). Incluyen una réplica exacta del sistema de archivos y están pensadas para ser restauradas tal y como fueron capturadas.
 
-- Consultar el listado de imágenes disponibles en un repositorio.
+- **Imágenes Git:**  
+    Imágenes incrementales gestionadas mediante un repositorio Git. A través del componente oggit, es posible registrar cambios entre versiones de una misma partición y transferir solo las diferencias entre el origen y el destino. Orientadas a entornos con cambios frecuentes y necesidades de optimización de ancho de banda.
 
-- Eliminar imágenes no utilizadas.
+#### Ficheros asociados a imágenes monolíticas
 
-- Descargar o importar imágenes desde otros servidores o dispositivos.
+- `*.img`: Fichero de imagen comprimida.
+- `*.sum`: Suma de verificación (MD5) de la imagen.
+- `*.size`: Tamaño de la imagen comprimida.
+- `*.info.checked`: Metainformación verificada de la imagen (tipo de compresor, tamaño real, cliente origen, etc.).
+- `*.torrent`: Archivo de metadatos necesario para las transferencias de tipo P2P.
 
-- Asignar imágenes a un determinado cliente o grupo de clientes.
+### Acciones disponibles en la interfaz web
 
+- Consultar el listado de imágenes disponibles en el repositorio.
+- Ver los detalles técnicos de cada imagen: nombre, tamaño, cliente origen, partición, tipo de clonador, etc.
+- Comprobar su integridad mediante sumas de verificación.
+- Importar imágenes externas previamente generadas.
+- Exportar imágenes para su traslado o respaldo en otros entornos.
+- Eliminar imágenes individualmente o en bloque.
 
-El sistema permite dos tipos de imágenes, cada una con sus propias características y casos de uso.
+### Consideraciones
 
-## Tipos de imágenes
-
-1. Imágenes monolíticas
-Las imágenes monolíticas almacenan el contenido completo del sistema de archivos del cliente en un único fichero comprimido. Estas imágenes se crean a partir de un cliente configurado previamente y se restauran íntegramente sobre otro equipo, sobrescribiendo su contenido.
-
-El fichero resultante suele tener extensión .img y se almacena en el repositorio asignado al cliente.
-
-No es posible restaurar parcialmente una imagen monolítica: siempre se transfiere el contenido completo, incluso si sólo han cambiado unos pocos ficheros.
-
-Su uso es recomendado cuando se desea una imagen "maestra" estable y uniforme para ser desplegada en múltiples equipos de un aula o laboratorio.
-
-2. Imágenes Git
-Las imágenes Git permiten almacenar los cambios realizados en el sistema de archivos en un repositorio Git. A diferencia del enfoque monolítico, esta modalidad permite controlar versiones, gestionar ramas y realizar operaciones como sincronización o copia incremental.
-
-Cada imagen se guarda en un repositorio .git bajo el directorio /opt/opengnsys/images/.
-
-Es posible restaurar únicamente los cambios realizados desde una versión anterior.
-
-Esta funcionalidad es gestionada por el componente complementario oggit, y se trata más adelante en este manual.
-
-Nota: Aunque ambas imágenes se almacenan en el mismo servidor, utilizan formatos distintos y no son intercambiables.
-
-
-## Consideraciones
 - Cada cliente debe tener asignado un repositorio de imágenes en su configuración. Las imágenes creadas se almacenarán en dicho repositorio.
-
-- Las imágenes deben ser creadas a partir de clientes previamente arrancados mediante ogLive, y correctamente preparados (sin usuarios conectados, sin procesos en ejecución críticos, etc.).
-
+- Las imágenes deben ser creadas a partir de clientes previamente arrancados mediante ogLive y correctamente preparados (sin usuarios conectados, sin procesos en ejecución críticos, etc.).
 - Se recomienda mantener una nomenclatura clara y estandarizada para facilitar la identificación de las imágenes.
-
 - El espacio del servidor debe ser suficiente para albergar las imágenes generadas, especialmente en el caso de restauraciones o sincronizaciones masivas.
 
+---
+
+## Alta de un repositorio en la GUI
+
+1. Entra en la interfaz web de OpenGnsys con un usuario administrador.
+2. En el menú lateral, pulsa **Repositorios**.  
+     ![oggui-ogrepository-main.png](../assets/images/screenshots/oggui-ogrepository-main.png)
+3. Pulsa **Añadir repositorio**.  
+     ![oggui-ogrepository-repository-options.png](../assets/images/screenshots/oggui-ogrepository-repository-options.png)
+4. Rellena el formulario:
+        - **Nombre del repositorio:** Un identificador legible (p. ej. `repository-test`).
+        - **IP:** La IP del servidor ogRepository (p. ej. `192.168.3.3`).
+        - **Puerto SSH:** Valor que utilizará el sistema para algunas acciones como transferir imágenes (p. ej. `22`).
+        - **Usuario:** Usuario de sistema con el que ogCore se conectará al repositorio (p. ej. `opengnsys`).
+        - **Comentarios:** Información adicional (Opcional).
+5. Pulsa **Guardar**.
+
+---
+
+### Comprobación rápida
+
+- Tras guardar, el nuevo registro debe aparecer en la tabla de **Administrar repositorios**.
+- Usa el botón **Imágenes monolíticas** del repositorio para abrir el inventario de imágenes. Si todo está correcto, verás la lista y podrás pulsar **Ver información** para inspeccionar el JSON.  
+    ![oggui-ogrepository-repository-info.png](../assets/images/screenshots/oggui-ogrepository-repository-info.png)
+
+> **Nota:**  
+> Los inventarios que se muestran provienen de `repoinfo.json` / `trashinfo.json` en el servidor ogRepository.  
+> Si el repositorio es nuevo, estos ficheros estarán vacíos hasta que se cree la primera imagen desde un cliente.
+
+---
+
+## Asignar un repositorio a un cliente
+
+1. Ve a **Grupos** (o al listado donde gestionas los clientes).
+2. En la tarjeta del cliente, abre el menú ⋮ y pulsa **Editar**.  
+3. En el formulario, localiza el campo **Repositorios** y selecciona el repositorio que acabas de crear (p. ej. `repository-test`).
+4. Revisa el resto de campos (OgLive, interfaz, MAC, IP, plantilla PXE, etc.) y pulsa **Guardar**.
+![oggui-ogrepository-asign-repository-client.png](../assets/images/screenshots/oggui-ogrepository-asign-repository-client.png)
+
+### ¿Qué implica esta asignación?
+
+- Ese cliente tendrá acceso a las imágenes almacenadas en el repositorio asignado, pudiendo restaurar cualquiera de ellas según sea necesario.
+- Las imágenes creadas desde ese cliente se guardarán automáticamente en el repositorio seleccionado.
+- Si tienes varios repositorios, puedes asignar repos diferentes a distintos clientes o aulas, optimizando el tráfico de red.
+
+---
+
+## Verificación
+
+- Desde **Repositorios → Imágenes monolíticas** del repo asignado, confirma que la imagen objetivo existe.
+- En el cliente (cuando arranque ogLive), podrás lanzar operaciones que consumirán este repositorio.
+
+---
+
+## Añadir manualmente una imagen al repositorio
+
+En algunos casos, puede ser necesario importar manualmente una imagen monolítica ya existente en el sistema de archivos del servidor ogRepository. Este proceso es útil cuando una imagen `.img` ha sido generada previamente o transferida desde otro servidor, y no ha sido registrada aún en la base de datos del componente.
+Para añadir una imagen manualmente, sigue estos pasos:
+
+### 1. Renombrar la imagen
+
+El archivo `.img` debe tener un nombre válido, sin espacios ni caracteres especiales, y sin la extensión al ser registrado en la interfaz. Por ejemplo, si la imagen representa un sistema Ubuntu BIOS, se puede renombrar de la siguiente manera:
+
+```bash
+mv imagen.img /opt/opengnsys/ogrepository/images/ubuntu-imagen-bios-documentation.img
+```
+
+>  **Importante:**  
+> Asegúrate de que el nombre no contenga la extensión `.img` al registrarlo en la interfaz (solo el nombre base será introducido).
+
+### 2. Mover la imagen al directorio de imágenes
+
+La imagen debe ubicarse en el directorio gestionado por ogRepository:
+
+Ejemplo:
+
+```bash
+mv ubuntu-imagen-bios-documentation.img /opt/opengnsys/ogrepository/images/
+```
+
+### 3. Ajustar los permisos
+
+Es necesario que el archivo `.img` tenga como propietario el usuario `opengnsys` para que el backend pueda manipularlo correctamente:
+
+```bash
+chown opengnsys:opengnsys /opt/opengnsys/ogrepository/images/ubuntu-imagen-bios-documentation.img
+chmod 744 /opt/opengnsys/ogrepository/images/ubuntu-imagen-bios-documentation.img
+```
+
+### 4. Importar la imagen desde la interfaz web
+
+Una vez el archivo esté correctamente ubicado y con los permisos apropiados, se debe registrar en el sistema desde la interfaz web:
+
+- Accede al apartado **Repositorio** de la interfaz de OpenGnsys.
+- Haz clic en el botón **Importar imagen**.
+- Se abrirá una ventana emergente solicitando el nombre de la imagen.
+- Introduce el nombre sin la extensión:
+
+    ```
+    ubuntu-imagen-bios-documentation
+    ```
+
+- Haz clic en **Continuar**.
+![Añadir imagen](oggui-ogrepository-repository-add-image.png)
+---
+
+## Acciones disponibles sobre una imagen
+
+Desde la interfaz de ogRepository, es posible gestionar las imágenes monolíticas mediante un menú contextual que aparece junto al icono de opciones (⋮). Este menú permite ejecutar distintas acciones sobre una imagen ya registrada en el repositorio.
+
+![Opciones de imagen](oggui-ogrepository-repository-options.png)
+
+A continuación se describen todas las acciones disponibles:
+
+### Obtener ficheros auxiliares
+
+Esta opción genera los archivos auxiliares necesarios para que la imagen pueda ser desplegada correctamente en los clientes. Los archivos generados incluyen:
+
+- `.torrent`: archivo para transmisiones P2P.
+- `.sum`: hash de verificación de integridad (SHA256).
+- `.info.checked`: metadatos de validación (tamaño, hash, tipo de sistema de archivos, etc.).
+- `.size`: tamaño en bloques de la imagen, usado en el cálculo de progreso de restauración.
+- `.meta`: archivo opcional con metainformación adicional.
+
+**Nota:** Esta acción debe ejecutarse siempre tras importar manualmente una imagen al repositorio.
+
+### Eliminar permanentemente
+
+Elimina completamente la imagen del repositorio, tanto en la base de datos como en el sistema de archivos del servidor. Esta acción es irreversible.
+
+**Nota:** Si la imagen fue eliminada previamente, pero aún está en papelera, esta opción la elimina definitivamente.
+
+### Recuperar imagen de la papelera
+
+Permite restaurar una imagen previamente eliminada, que ha sido enviada a la papelera lógica del sistema. La imagen volverá a estar disponible para uso inmediato.
+
+**Nota:** Esta opción solo está activa si la imagen se encuentra en estado "eliminado".
+
+### Transferir imagen
+
+Permite transferir la imagen desde el servidor actual a otro servidor ogRepository de la red. Se debe especificar la IP, puerto SSH y usuario del servidor destino. La transferencia se realiza mediante SCP y requiere que el usuario tenga permisos de escritura en el directorio de imágenes del servidor destino.
+
+![Transferir imagen](oggui-ogrepository-repository-transferir-image.png)
+
+**Nota:** Esta función es útil para clonar imágenes entre servidores sin necesidad de exportarlas manualmente.
+
+### Transferir imagen globalmente
+
+Similar a la opción anterior, pero la imagen se marca como "global" una vez completada la transferencia. Las imágenes globales están disponibles para ser vistas y utilizadas por todos los servidores de la red, según la configuración distribuida de OpenGnsys.
+
+**Nota:** Requiere permisos administrativos y configuración previa de los nodos de red.
+
+### Realizar backup
+
+Genera una copia de seguridad de la imagen actual. El destino del backup puede ser configurado, ya sea en otro disco local o en un servidor remoto (NFS, SSH, etc.).
+
+La copia puede incluir solo el archivo `.img` o todos los archivos asociados a la imagen.
+
+### Checkear estado imagen
+
+Verifica la integridad de la imagen comprobando que:
+
+- El archivo `.img` existe y es accesible.
+- El archivo `.sum` coincide con el hash actual del `.img`.
+- Los archivos auxiliares están presentes y no están corruptos.
+
+Esta opción es útil para diagnosticar errores antes de realizar una restauración.
 
 
+### Renombrar imagen
+
+Permite modificar el nombre lógico de la imagen dentro del sistema, actualizando su referencia en la base de datos.
+
+**Nota:** Esta acción no renombra el archivo físico en el sistema de archivos. Solo afecta al nombre mostrado y registrado en la base de datos.