oggit documentation and images

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

@@ -0,0 +1,357 @@
+# OgGit - Gestión de imágenes Git
+
+## Introducción a OgGit
+
+El componente OgGit está diseñado para gestionar un tipo de imagen de sistema: las imágenes Git. A diferencia de las imágenes monolíticas gestionadas por ogRepository, las imágenes Git permiten capturar el contenido completo de una partición y versionarlo dentro de un repositorio Git, proporcionando una solución robusta y eficiente para el control de cambios, auditoría y reversión de estados en entornos de laboratorio y aula.
+
+Las imágenes Git se crean a partir de una partición del sistema (por ejemplo, un sistema operativo Windows o Linux previamente instalado), y una vez generadas, son almacenadas en un servidor Forgejo, una instancia de Git autoalojada y adaptada para la gestión de múltiples repositorios desde el entorno web. Estas imágenes permiten no solo capturar el estado del sistema en un momento dado, sino también realizar commits incrementales, clonar configuraciones, recuperar archivos individuales y comparar versiones, entre otras operaciones avanzadas.
+
+El flujo de trabajo de OgGit se apoya en varias capas:
+
+- Captura del contenido del sistema: se extraen todos los archivos y carpetas de una partición del cliente.
+
+- Inicialización y mantenimiento de repositorios Git: cada imagen Git se guarda como un repositorio individual en Forgejo, que permite operaciones estándar de Git como commits, ramas, merges o clonado.
+
+- Visualización y gestión desde el interfaz web: gracias a la integración con Forgejo, los administradores pueden consultar el historial de cambios, explorar el contenido del sistema capturado y verificar auditorías desde una interfaz visual.
+
+## ¿Por qué usar imágenes Git?
+
+Las imágenes Git representan una evolución en la gestión de sistemas, especialmente útil en entornos educativos, de desarrollo o pruebas, donde los equipos pueden cambiar constantemente. Sus ventajas incluyen:
+
+- **Versionado completo** del sistema.
+- **Acceso a contenido granular** (ver archivos modificados).
+- **Restauraciones más rápidas** y específicas.
+
+
+## Acceso a la gestión de imágenes Git
+
+1. En el menú lateral izquierdo, haz clic en `Repositorios`.
+2. Localiza el repositorio deseado.
+3. Haz clic en el botón de gestión Git para acceder a la gestión de commits del repositorio seleccionado.
+
+![Acceso a imágenes Git](../assets/images/screenshots/oggui-ogrepository-oggui-menu-access.png)
+
+---
+
+## Lista de commits
+
+Una vez dentro del menú de gestión Git del repositorio, se muestra una tabla con todos los commits disponibles en la rama seleccionada.
+
+- Puedes cambiar de repositorio y rama desde los desplegables superiores.
+- También puedes buscar commits por mensaje.
+- La tabla muestra información básica como el ID del commit, el mensaje, la fecha, el tamaño, el número de archivos modificados y los tags asignados.
+
+![Lista de commits Git](../assets/images/screenshots/oggui-ogrepository-oggui-menu.png)
+
+### Acciones disponibles por commit
+
+En la columna de acciones (última columna), se pueden realizar las siguientes operaciones:
+
+- Ver archivos modificados (si los hay).
+- Ver detalles del commit.
+- Asignar etiquetas (tags).
+- Restaurar el sistema al estado de ese commit.
+
+---
+
+## Ver detalles del commit
+
+Al pulsar el botón de detalles, se abre un cuadro modal con los datos completos del commit seleccionado:
+
+- Commit ID
+- Mensaje
+- Fecha
+- Tamaño
+- Número de archivos modificados
+- Líneas añadidas y eliminadas
+- Tags asignados
+
+![Detalles del commit](../assets/images/screenshots/oggui-ogrepository-oggui-commit-details.png)
+
+---
+
+## Ver información del repositorio
+
+En la esquina superior derecha de la ventana de commits se encuentra el botón `Ver información`. Al pulsarlo, se muestra un resumen con los metadatos del repositorio Git:
+
+- Nombre del repositorio
+- UUID
+- Rama seleccionada
+- Total de repositorios Git disponibles
+- Total de ramas
+- Total de commits
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-repository-details.png)
+
+---
+
+## Notas
+
+- Estas imágenes Git se generan automáticamente desde la partición del sistema del cliente, y son útiles para mantener una trazabilidad de los cambios realizados.
+- Puedes utilizar esta sección para auditar el historial de cambios, clonar imágenes entre clientes o realizar restauraciones específicas desde un commit.
+- Los repositorios Git están gestionados internamente por el componente `OgGit`, y pueden consultarse a través de la API REST o desde la interfaz web oggui.
+
+
+## Crear imagen Git
+
+### Requisitos Previos y Consideraciones Críticas
+Antes de iniciar el proceso, verifique que se cumplen las siguientes condiciones en el cliente. Ignorarlos puede resultar en una imagen corrupta, incompleta o en fallos durante la captura.
+
+### Requisitos previos para crear una imagen Git
+
+1. **Sistema estable e íntegro**  
+    - El sistema operativo del cliente debe estar libre de errores de archivos, configuraciones corruptas y fallos de hardware.
+    - _Recomendación:_ Ejecute comprobaciones de integridad del disco (por ejemplo, `chkdsk /f` en Windows o `fsck` en Linux) y asegúrese de que el sistema arranca sin errores.
+
+2. **Deshabilitar compresión de sistema**  
+    - Los directorios del sistema no deben estar comprimidos mediante herramientas como compresOS o la compresión nativa de Windows NTFS.
+    - _Cómo comprobarlo:_  
+      - **Windows:** Ejecuta `fsutil fsinfo volumeinfo C:` y verifica que `Supports File-based Compression` esté deshabilitado.  
+      - **Linux:** Comprueba que no se utilicen sistemas de archivos comprimidos (por ejemplo, revisa las opciones de montaje en `/etc/fstab`).
+
+3. **Espacio suficiente en la partición de caché**  
+    - El cliente debe disponer de una partición de caché con espacio libre suficiente para almacenar temporalmente todos los datos extraídos.
+    - _Regla general:_ El espacio libre debe ser al menos 1.5 veces el tamaño de los datos utilizados en la partición de origen. La falta de espacio provocará el aborto inmediato del proceso.
+
+
+Asegúrate de cumplir estos requisitos antes de continuar con los pasos detallados a continuación para garantizar una imagen Git fiable y utilizable.
+El proceso de creación de una imagen Git se puede dividir en varias fases:
+
+1. **Selección del cliente modelo** encendido en Oglive.
+2. **Elección del repositorio Git** (o creación de uno nuevo en caso de que sea la primera vez que se crea una imagen Git para ese cliente).
+3. **Selección de la partición del disco** concretamente la que contiene el sistema operativo a capturar.
+4. **Ejecución del comando** y seguimiento desde la traza de ejecución.
+
+### Paso 1: Acceder a la acción "Crear imagen"
+
+Desde el panel de administración web:
+
+- Ir a la pestaña **Grupos**.
+- Seleccionar la **Unidad Organizativa** deseada.
+- Localizar el cliente encendido que actuará como equipo modelo.
+- Pulsar el icono de acciones del cliente.
+- Elegir **Crear imagen**.
+
+
+
+### Paso 2: Seleccionar tipo de imagen "Git"
+
+En el formulario de creación de imagen, se muestra por defecto la opción **Monolítica**. Para trabajar con OgGit:
+
+- Desplegar el selector de **Tipo de imagen**.
+- Seleccionar la opción **Git**.
+
+Esto activará nuevas secciones específicas para la configuración Git.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-create-image-new-repository.png)
+
+
+### Paso 3: Crear un nuevo repositorio
+
+Si es la primera vez que se crea una imagen Git para ese cliente, es necesario crear un nuevo repositorio asociado. Para ello:
+
+- Pulsar el botón **Crear nuevo repositorio / SO**.
+- Introducir un nombre identificativo, por ejemplo: `windows11-documentation`.
+- Pulsar **Guardar**.
+
+Una vez creado el repositorio, quedará vinculado al cliente y aparecerá en el selector desplegable para futuras operaciones.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-create-image-new-repository-add-name.png)
+
+
+> **Un solo repositorio por cliente:**  
+> Cada cliente solo puede tener asociado un único repositorio Git. Si ya existe uno, no podrá crearse un segundo.
+
+### Paso 4: Seleccionar partición del disco
+
+A continuación se presenta una tabla con las particiones detectadas en el cliente:
+
+- Disco y número de partición
+- Tamaño en MB
+- Tipo de partición (EFI, WINDOWS, CACHE, etc.)
+- Sistema de ficheros (NTFS, EXT4, etc.)
+- Sistema operativo detectado
+
+Seleccionar aquella partición que contenga el sistema operativo que se desea capturar, por ejemplo:
+
+> Disco 1, Partición 3: NTFS, Windows 11 Home 64 bits.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-create-image-new-repository-select-partition.png)
+
+
+### Paso 5: Ejecutar la acción y seguimiento
+
+Una vez configurado el repositorio y seleccionada la partición:
+
+- Pulsar el botón **Ejecutar**.
+- Se iniciará el proceso de captura y aparecerá una nueva entrada en el panel de **Trazas de ejecución**.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-create-image-new-repository-traza.png)
+
+
+El cliente arrancado con ogLive mostrará en su pantalla local los comandos en ejecución. Se puede observar, por ejemplo, el montaje del repositorio Git remoto en `/mnt/sda3` y la ejecución del script `crearImagenGit`.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-create-image-new-repository-traza-client.png)
+
+
+#### Duración y rendimiento
+
+La duración del proceso depende de:
+
+- Tamaño de la partición.
+- Número de ficheros y cambios detectados.
+- Velocidad de lectura/escritura en disco.
+- Conectividad con el servidor del repositorio.
+
+En sistemas con gran volumen de datos (como Windows 11 con varias particiones) el proceso puede extenderse varios minutos.
+
+---
+
+## Visualizar el repositorio en Forgejo
+
+Una vez creada la imagen Git, esta puede consultarse desde la interfaz Forgejo:
+
+1. Entrar en la dirección web del servidor de Git (Forgejo).
+2. Navegar al repositorio del cliente, por ejemplo `oggit/windows11-lgromero`.
+
+Se pueden explorar:
+
+- Archivos y directorios del sistema capturado.
+- Historial de commits.
+- Diferencias entre versiones.
+- Cambios en binarios y textos.
+
+Esto permite una inspección avanzada del contenido exacto capturado, ideal para diagnóstico y auditoría.
+
+
+## Restauración de una Imagen Git
+
+### Introducción
+
+El proceso de restauración de una imagen Git permite desplegar una versión específica de un sistema capturado previamente en uno o más clientes. A diferencia de las imágenes monolíticas, las imágenes Git permiten seleccionar puntos concretos de restauración (commit, rama, tag) gracias al control de versiones.
+
+### Requisitos Previos
+
+- Tener al menos una imagen Git creada y almacenada en un repositorio Forgejo/Gitea.
+- El cliente destino debe tener asignado un repositorio en su configuración.
+- El cliente debe estar particionado previamente con el tamaño adecuado y el sistema de archivos correcto.
+- El cliente debe tener partición CACHE.
+- El cliente en estado ogLive para realizar la operación.
+
+### Procedimiento de Restauración
+
+#### Paso 1. Acceder a la Herramienta de Despliegue
+
+Desde el panel de administración web:
+
+- Ir a la pestaña **Grupos**.
+- Seleccionar la **Unidad Organizativa** deseada.
+- Localizar el cliente encendido que actuará como equipo modelo.
+- Pulsar el icono de acciones del cliente.
+- Elegir **Desplegar imagen**.
+
+### Paso 2: Seleccionar tipo de imagen "Git"
+
+En el formulario de creación de imagen, se muestra por defecto la opción **Monolítica**. Para trabajar con OgGit:
+
+- Desplegar el selector de **Tipo de imagen**.
+- Seleccionar la opción **Git**.
+
+Esto activará nuevas secciones específicas para la configuración Git.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-restore-image-repository.png)
+
+#### 3. Especificar la Versión de la Imagen
+
+| Parámetro               | Ejemplo                                      | Descripción                                      |
+|-------------------------|----------------------------------------------|--------------------------------------------------|
+| Tipo de imagen          | Git                                          | Seleccione "Git" como tipo de imagen             |
+| Seleccionar Repositorio | windows11-documentation                      | Elija el repositorio que contiene la imagen      |
+| Seleccionar Rama        | main                                         | Seleccione la rama del repositorio               |
+| Commit ID               | a7915357bc7b337cf49c59bee6d4242e578ab44      | Identificador hash del commit específico         |
+| Mensaje                 | creating git image                           | Mensaje descriptivo para la operación            |
+| Fecha                   | 11/09/2025 10:02:08                          | Fecha y hora de la versión a restaurar           |
+| Tags                    | opcional                                     | Etiquetas para categorizar la operación          |
+
+#### 4. Selección de Partición de Destino
+
+Seleccione la partición donde desea restaurar la imagen:
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-restore-image-repository-select-partition.png)
+
+#### 5. Opciones de Ejecución
+
+- **Ejecutar:** Inicia la restauración inmediatamente.
+- **Generar instrucciones:** Crea un script para ejecutar la restauración manualmente.
+- **Opciones de programación:** Permite programar la restauración para una fecha futura.
+
+---
+
+### Consideraciones Importantes
+
+- **Restauración Incremental:** La restauración de imágenes Git solo transfiere los cambios respecto a la versión actual, optimizando tiempo y ancho de banda.
+- **Conectividad:** Asegúrese de que el cliente tenga conexión de red estable con el servidor Forgejo/Gitea durante el proceso.
+- **Compatibilidad:** Verifique que la imagen Git sea compatible con el hardware del cliente destino.
+- **Espacio en Disco:** Confirme que la partición de destino tenga espacio suficiente para la imagen restaurada.
+    
+
+## Ejemplo práctico:
+### Ejemplo práctico: Organización de ramas y tags en OgGit
+
+Supongamos que partimos de un repositorio con la siguiente estructura inicial:
+
+```
+main (rama principal)
+├── v1.0-estable (tag)
+└── desarrollo (rama)
+    └── experimentos varios
+```
+
+El objetivo es evolucionar el repositorio siguiendo buenas prácticas para llegar a:
+
+```
+main (rama principal)
+├── v1.0-estable (tag)
+├── v1.1-autocad (tag)
+├── profesor-autocad (rama)
+│   ├── commit: instalación base
+│   └── commit: configuración AutoCAD
+└── desarrollo (rama)
+    └── experimentos varios
+```
+
+#### Pasos recomendados
+
+1. **Crear una rama específica para el profesor**
+   - Desde la interfaz de OgGit, selecciona el commit base en `main` y crea una nueva rama llamada `profesor-autocad`.
+   - Esto permite trabajar en configuraciones específicas sin afectar la rama principal.
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-example-create-branch.png)
+
+2. **Realizar commits temáticos**
+   - En la rama `profesor-autocad`, realiza un commit tras instalar la base del sistema.
+   - Realiza un segundo commit tras instalar y configurar AutoCAD.
+   - Añade mensajes descriptivos para cada commit, por ejemplo:  
+     - `instalación base`
+     - `configuración AutoCAD`
+
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-example-create-image-professor.png)
+
+3. **Etiquetar versiones estables**
+   - Una vez verificado el funcionamiento, asigna un tag a la rama principal (`main`) tras fusionar los cambios relevantes, por ejemplo:  
+     - `v1.1-autocad`
+![Información del repositorio](../assets/images/screenshots/oggui-ogrepository-oggui-example-branch-professor-create-tag-autocad.png)
+4. **Mantener ramas de desarrollo separadas**
+   - Continúa usando la rama `desarrollo` para pruebas y experimentos, evitando mezclar cambios no validados en `main` o `profesor-autocad`.
+
+#### Buenas prácticas
+
+- Utiliza ramas para separar configuraciones o perfiles de usuario (por ejemplo, profesor, alumno, laboratorio).
+- Realiza commits frecuentes y descriptivos para facilitar auditoría y restauración.
+- Usa tags para marcar versiones estables y facilitar despliegues.
+- Fusiona cambios a `main` solo tras validar que funcionan correctamente.
+
+#### Resultado final
+
+El repositorio mostrará una estructura clara y organizada, facilitando restauraciones específicas, auditoría y gestión eficiente de versiones.
+

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

@@ -1,24 +1,37 @@
 ## Introducción a ogRepository
 
-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.
 
-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.
 
-### Tipos de imágenes compatibles
+El componente **ogRepository** se encarga de almacenar, gestionar y distribuir las imágenes del sistema operativo utilizadas para clonar equipos en entornos de laboratorio o aula.
 
-- **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.
+Funciona en conjunción con el `ogServer` y los clientes, proporcionando una interfaz web centralizada para realizar todas las operaciones de gestión: visualización, importación, exportación, verificación de integridad y eliminación de imágenes.
 
-- **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.
+### Arquitectura y Flujo de Trabajo
+1.  **Creación:** Las imágenes se crean desde un cliente arrancado via `ogLive`.
+2.  **Almacenamiento:** Se almacenan en el directorio del `ogRepository` asignado a ese cliente.
+3.  **Consulta:** El `ogServer` consulta al repositorio para obtener la lista de imágenes disponibles.
+4.  **Restauración:** Durante una operación de clonación, la máquina cliente descarga la imagen desde el repositorio (vía Unicast, Multicast o P2P/BitTorrent).
 
-#### Ficheros asociados a imágenes monolíticas
+## Tipos de Imágenes Gestionadas
 
-- `*.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.
+ogRepository es compatible con dos tipos de imágenes, cada una diseñada para diferentes casos de uso:
+
+| Tipo | Descripción | Formato | Caso de Uso Ideal |
+| :--- | :--- | :--- | :--- |
+| **Imágenes Monolíticas** | Captura completa y comprimida de una partición. Es una réplica exacta del sistema de archivos en el momento de la captura. | Archivo `*.img.zst` (compresión Zstandard) | Entornos estables, imágenes base inmutables, restauraciones rápidas y sencillas. |
+| **Imágenes Git** | Imágenes versionadas que almacenan cambios incrementales. Gestionadas por el componente `OgGit`. | Repositorio Git (normalmente en Forgejo/Gitea) | Entornos con cambios frecuentes, needing auditoría de cambios, reversión de estados y optimización de espacio y ancho de banda. |
+
+### Archivos Asociados a Imágenes Monolíticas
+
+Cada imagen monolítica genera una serie de archivos auxiliares esenciales para su gestión e integridad:
+
+| Archivo | Propósito |
+| :--- | :--- |
+| **`<nombre>.img.zst`** | La imagen comprimida en sí misma (formato Zstandard). |
+| **`<nombre>.sum`** | Suma de verificación SHA256 para validar la integridad del archivo de imagen. |
+| **`<nombre>.size`** | Contiene el tamaño de la imagen comprimida, usado para cálculos de progreso. |
+| **`<nombre>.info.checked`** | Metadatos de la imagen (cliente origen, partición, tipo de compresor, tamaño real, etc.). |
+| **`<nombre>.torrent`** | Metadatos para habilitar la distribución eficiente de la imagen via protocolo BitTorrent (P2P). |
 
 ### Acciones disponibles en la interfaz web
 
@@ -75,7 +88,7 @@ A través de la consola web de administración, ogRepository ofrece una interfaz
 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?
+Esta asignación tiene las siguientes implicaciones:
 
 - 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.

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

@@ -40,7 +40,7 @@ Antes de definir una tabla de particiones se recomienda tener en cuenta:
 | FREEBSD, SOLARIS, …    | Sistemas nativos correspondientes       | Para sistemas alternativos (no habituales)               |
 
 !!! note "Nota"
-    El sistema identifica partición CACHE como tal, pero internamente utiliza un sistema de archivos EXT4 con configuración específica.
+    El sistema identifica partición CACHE como tal, pero internamente utiliza un sistema de archivos EXT4 con configuración específica. Sin embargo es importante marcar el tipo CACHE para que OpenGnsys la gestione correctamente.
 
 
 ## La partición CACHE

i18n-docu/mkdocs.yml

@@ -120,6 +120,7 @@ nav:
     - Motor de Clonación: administration/ogcloneengine.md
     - Gestión de discos y particiones: administration/particionador.md
     - Gestión de Repositorios: administration/ogrepository.md
+    - Gestión de Imágenes Git: administration/oggit.md
     - ogAgent: administration/ogagent.md
     - Logs y Monitorización: administration/oglog.md
   - Desarrolladores: