1829 lines
44 KiB
Markdown
1829 lines
44 KiB
Markdown
# ogCore - Documentación Técnica y Funcional
|
|
|
|
## Tabla de Contenidos
|
|
|
|
1. [Introducción](#1-introducción)
|
|
2. [Descripción del Proyecto](#2-descripción-del-proyecto)
|
|
3. [Arquitectura del Sistema](#3-arquitectura-del-sistema)
|
|
4. [Tecnologías Utilizadas](#4-tecnologías-utilizadas)
|
|
5. [Requisitos del Sistema](#5-requisitos-del-sistema)
|
|
6. [Instalación y Configuración](#6-instalación-y-configuración)
|
|
7. [Modelo de Datos](#7-modelo-de-datos)
|
|
8. [Componentes del Sistema](#8-componentes-del-sistema)
|
|
9. [API RESTful](#9-api-restful)
|
|
10. [Seguridad y Autenticación](#10-seguridad-y-autenticación)
|
|
11. [Servicios Principales](#11-servicios-principales)
|
|
12. [Comandos de Consola](#12-comandos-de-consola)
|
|
13. [Migraciones de Datos](#13-migraciones-de-datos)
|
|
14. [Testing](#14-testing)
|
|
15. [Despliegue](#15-despliegue)
|
|
16. [Mantenimiento y Operaciones](#16-mantenimiento-y-operaciones)
|
|
17. [Integración con Otros Servicios](#17-integración-con-otros-servicios)
|
|
18. [Roadmap y Changelog](#18-roadmap-y-changelog)
|
|
19. [Contribución](#19-contribución)
|
|
20. [Soporte y Contacto](#20-soporte-y-contacto)
|
|
|
|
---
|
|
|
|
## 1. Introducción
|
|
|
|
**ogCore** es el servicio central de **OpenGnsys**, una plataforma de código abierto diseñada para la gestión centralizada de aulas de informática, laboratorios y entornos educativos. Este servicio proporciona una API RESTful robusta que permite administrar de manera eficiente clientes (equipos), imágenes de sistemas operativos, perfiles de hardware y software, tareas programadas, y mucho más.
|
|
|
|
### 1.1 Propósito del Sistema
|
|
|
|
El propósito principal de ogCore es:
|
|
|
|
- **Centralizar la gestión** de equipos informáticos en entornos educativos y corporativos
|
|
- **Automatizar el despliegue** de sistemas operativos e imágenes
|
|
- **Gestionar inventarios** de hardware y software
|
|
- **Programar y ejecutar tareas** de manera automática
|
|
- **Proporcionar trazabilidad** de todas las operaciones realizadas
|
|
- **Facilitar la migración** desde versiones anteriores de OpenGnsys
|
|
|
|
### 1.2 Alcance
|
|
|
|
ogCore gestiona:
|
|
- Clientes (equipos físicos)
|
|
- Imágenes de sistemas operativos
|
|
- Repositorios de imágenes
|
|
- Perfiles de hardware y software
|
|
- Unidades organizativas (aulas, grupos)
|
|
- Redes y subredes
|
|
- Plantillas PXE
|
|
- Menús de arranque
|
|
- Comandos y tareas programadas
|
|
- Trazas de ejecución
|
|
- Calendarios remotos
|
|
- Integración con sistemas externos (UDS, ogRepository, ogDhcp, ogBoot)
|
|
|
|
---
|
|
|
|
## 2. Descripción del Proyecto
|
|
|
|
### 2.1 ¿Qué es ogCore?
|
|
|
|
ogCore es el núcleo central de OpenGnsys desarrollado con tecnologías modernas de PHP. Actúa como backend que expone una API RESTful completa, permitiendo la gestión de todos los aspectos relacionados con la administración de aulas informáticas.
|
|
|
|
### 2.2 Características Principales
|
|
|
|
- **API RESTful completa** con documentación Swagger/OpenAPI
|
|
- **Autenticación JWT** con refresh tokens
|
|
- **Arquitectura basada en eventos** con notificaciones en tiempo real (Mercure)
|
|
- **Sistema de colas** para la ejecución de tareas programadas
|
|
- **Integración con múltiples servicios** externos
|
|
- **Migraciones automatizadas** desde OpenGnsys 1.1
|
|
- **Versionado de imágenes** con integración Git
|
|
- **Sistema de trazabilidad** completo
|
|
- **Gestión de hardware** con inventario automático
|
|
- **Despliegues masivos** de imágenes (unicast, multicast, torrent, p2p)
|
|
- **Gestión de particiones** automática
|
|
- **Sistema de validación** robusto
|
|
|
|
### 2.3 Versión Actual
|
|
|
|
- **Versión**: 0.5.0
|
|
- **Estado**: En desarrollo activo
|
|
- **Última actualización**: Octubre 2025
|
|
|
|
---
|
|
|
|
## 3. Arquitectura del Sistema
|
|
|
|
### 3.1 Arquitectura General
|
|
|
|
ogCore sigue una arquitectura de **microservicios** basada en el patrón **API-First**:
|
|
|
|
```
|
|
+-------------------------------------------------------------+
|
|
| Frontend (Web UI) |
|
|
+---------------------------+----------------------------------+
|
|
|
|
|
| HTTP/REST
|
|
|
|
|
+---------------------------v---------------------------------+
|
|
| ogCore API (Symfony) |
|
|
| +------------------------------------------------------+ |
|
|
| | Controllers | States | DTOs | Validators | Filters | |
|
|
| +------------------------------------------------------+ |
|
|
| +------------------------------------------------------+ |
|
|
| | Business Logic (Services) | |
|
|
| +------------------------------------------------------+ |
|
|
| +------------------------------------------------------+ |
|
|
| | Entities | Repositories | Doctrine ORM | |
|
|
| +------------------------------------------------------+ |
|
|
+---------------------------+----------------+----------------+
|
|
| |
|
|
+------------------v--+ +--------v--------+
|
|
| MariaDB | | Mercure |
|
|
| Database | | (WebSocket) |
|
|
+---------------------+ +-----------------+
|
|
|
|
+-------------------------------------------------------------+
|
|
| Servicios Externos Integrados |
|
|
+--------------+--------------+--------------+----------------+
|
|
| ogRepository | ogDhcp | ogBoot | UDS/Git |
|
|
+--------------+--------------+--------------+----------------+
|
|
```
|
|
|
|
### 3.2 Capas de la Aplicación
|
|
|
|
#### 3.2.1 Capa de Presentación (API)
|
|
- **API Platform**: Framework para crear APIs REST
|
|
- **Controllers**: Controladores personalizados (102 controladores)
|
|
- **DTOs (Data Transfer Objects)**: 93 objetos de transferencia de datos
|
|
- **OpenAPI/Swagger**: Documentación automática de la API
|
|
|
|
#### 3.2.2 Capa de Negocio
|
|
- **Services**: Lógica de negocio (13 servicios principales)
|
|
- **Handlers**: Manejadores de eventos (2 handlers)
|
|
- **EventSubscribers**: Suscriptores de eventos (8 suscriptores)
|
|
- **Validators**: Validadores personalizados (18 validadores)
|
|
|
|
#### 3.2.3 Capa de Datos
|
|
- **Entities**: 35 entidades del modelo de datos
|
|
- **Repositories**: 32 repositorios personalizados
|
|
- **Doctrine ORM**: Mapeo objeto-relacional
|
|
- **Migrations**: 85 migraciones de base de datos
|
|
|
|
#### 3.2.4 Capa de Infraestructura
|
|
- **Docker**: Contenedorización de servicios
|
|
- **Nginx**: Servidor web reverse proxy
|
|
- **PHP-FPM**: Procesador de PHP
|
|
- **MariaDB**: Sistema de gestión de base de datos
|
|
- **Mercure**: Sistema de notificaciones en tiempo real
|
|
|
|
### 3.3 Patrones de Diseño Utilizados
|
|
|
|
1. **Repository Pattern**: Para abstracción de acceso a datos
|
|
2. **DTO Pattern**: Para transferencia de datos entre capas
|
|
3. **Factory Pattern**: Para creación de entidades complejas
|
|
4. **Event-Driven Architecture**: Para notificaciones y reactividad
|
|
5. **State Pattern**: Para gestión de estados de procesamiento
|
|
6. **Service Layer**: Para encapsulación de lógica de negocio
|
|
|
|
---
|
|
|
|
## 4. Tecnologías Utilizadas
|
|
|
|
### 4.1 Backend
|
|
|
|
| Tecnología | Versión | Propósito |
|
|
|------------|---------|-----------|
|
|
| **PHP** | 8.3 | Lenguaje de programación principal |
|
|
| **Symfony** | 6.4 | Framework web principal |
|
|
| **Doctrine ORM** | 2.19 | Mapeo objeto-relacional |
|
|
| **API Platform** | 3.2 | Creación de APIs REST |
|
|
| **Lexik JWT** | 3.0 | Autenticación JWT |
|
|
| **Gesdinet JWT Refresh Token** | 1.3 | Refresh tokens |
|
|
| **Stof Doctrine Extensions** | 1.10 | Extensiones de Doctrine (timestampable, etc.) |
|
|
| **Ramsey UUID** | 2.0 | Generación de UUIDs |
|
|
|
|
### 4.2 Base de Datos
|
|
|
|
| Tecnología | Versión | Propósito |
|
|
|------------|---------|-----------|
|
|
| **MariaDB** | 10.11 | Sistema de gestión de base de datos |
|
|
| **Doctrine DBAL** | 3.x | Capa de abstracción de base de datos |
|
|
| **Doctrine Migrations** | 3.3 | Gestión de migraciones |
|
|
|
|
### 4.3 Infraestructura
|
|
|
|
| Tecnología | Versión | Propósito |
|
|
|------------|---------|-----------|
|
|
| **Docker** | Latest | Contenedorización |
|
|
| **Docker Compose** | Latest | Orquestación de contenedores |
|
|
| **Nginx** | Latest | Servidor web / Reverse proxy |
|
|
| **PHP-FPM** | 8.3 | Procesador FastCGI |
|
|
| **Mercure** | 0.3.9 | Hub de notificaciones en tiempo real |
|
|
|
|
### 4.4 Testing
|
|
|
|
| Tecnología | Versión | Propósito |
|
|
|------------|---------|-----------|
|
|
| **PHPUnit** | 9.5 | Framework de testing |
|
|
| **Symfony PHPUnit Bridge** | 7.0 | Integración con Symfony |
|
|
| **DAMA Doctrine Test Bundle** | 8.1 | Transacciones de prueba |
|
|
| **Zenstruck Foundry** | 1.37 | Factories para testing |
|
|
|
|
### 4.5 Desarrollo
|
|
|
|
| Tecnología | Versión | Propósito |
|
|
|------------|---------|-----------|
|
|
| **Symfony Maker Bundle** | 1.59 | Generación de código |
|
|
| **Symfony Web Profiler** | 6.4 | Debugging y profiling |
|
|
| **Monolog** | 3.x | Logging |
|
|
| **PHPStan** | Latest | Análisis estático |
|
|
|
|
---
|
|
|
|
## 5. Requisitos del Sistema
|
|
|
|
### 5.1 Requisitos de Hardware (Producción)
|
|
|
|
- **CPU**: Mínimo 4 cores, recomendado 8+ cores
|
|
- **RAM**: Mínimo 8GB, recomendado 16GB+
|
|
- **Disco**:
|
|
- Sistema: 20GB SSD
|
|
- Base de datos: 50GB+ SSD
|
|
- Logs: 10GB
|
|
- **Red**: 1Gbps mínimo
|
|
|
|
### 5.2 Requisitos de Software
|
|
|
|
- **Sistema Operativo**: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
|
|
- **Docker**: >= 20.10
|
|
- **Docker Compose**: >= 2.0
|
|
- **Git**: >= 2.25 (para gestión de código)
|
|
|
|
### 5.3 Puertos Requeridos
|
|
|
|
| Puerto | Servicio | Propósito |
|
|
|--------|----------|-----------|
|
|
| 8080 | Nginx/HTTP | API y documentación |
|
|
| 3306 | MariaDB | Base de datos |
|
|
| 9000 | PHP-FPM | Procesador PHP |
|
|
| 3000 | Mercure | WebSocket/SSE |
|
|
|
|
---
|
|
|
|
## 6. Instalación y Configuración
|
|
|
|
### 6.1 Instalación con Docker (Recomendado)
|
|
|
|
#### 6.1.1 Clonar el Repositorio
|
|
|
|
```bash
|
|
git clone <url-del-repositorio> ogcore
|
|
cd ogcore
|
|
```
|
|
|
|
#### 6.1.2 Verificar Puertos Disponibles
|
|
|
|
Asegúrate de que los puertos 8080 y 3306 no estén en uso:
|
|
|
|
```bash
|
|
sudo lsof -i :8080
|
|
sudo lsof -i :3306
|
|
```
|
|
|
|
#### 6.1.3 Desplegar Contenedores
|
|
|
|
```bash
|
|
docker compose up --build -d
|
|
```
|
|
|
|
#### 6.1.4 Verificar Contenedores
|
|
|
|
```bash
|
|
docker ps
|
|
```
|
|
|
|
Deberías ver tres contenedores activos:
|
|
- `ogcore-nginx`
|
|
- `ogcore-php`
|
|
- `ogcore-database`
|
|
|
|
#### 6.1.5 Instalar Dependencias
|
|
|
|
```bash
|
|
docker exec ogcore-php composer install
|
|
```
|
|
|
|
#### 6.1.6 Generar Claves JWT
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console lexik:jwt:generate-keypair --overwrite
|
|
```
|
|
|
|
#### 6.1.7 Inicializar Base de Datos
|
|
|
|
```bash
|
|
# Ejecutar migraciones
|
|
docker exec ogcore-php php bin/console doctrine:migrations:migrate --no-interaction
|
|
|
|
# Cargar datos iniciales (fixtures)
|
|
docker exec ogcore-php php bin/console doctrine:fixtures:load --no-interaction
|
|
|
|
# Cargar grupos de usuarios por defecto
|
|
docker exec ogcore-php php bin/console app:load-default-user-groups
|
|
|
|
# Cargar comandos por defecto
|
|
docker exec ogcore-php php bin/console app:load-default-commands
|
|
```
|
|
|
|
#### 6.1.8 Acceder a la Aplicación
|
|
|
|
Abre tu navegador y accede a:
|
|
|
|
```
|
|
http://127.0.0.1:8080/docs
|
|
```
|
|
|
|
Deberías ver la documentación Swagger de la API de ogCore.
|
|
|
|
### 6.2 Configuración
|
|
|
|
#### 6.2.1 Variables de Entorno
|
|
|
|
El archivo `.env` contiene las variables de configuración principales:
|
|
|
|
```bash
|
|
# Entorno
|
|
APP_ENV=dev
|
|
APP_SECRET=<tu-secreto>
|
|
|
|
# Base de datos
|
|
DATABASE_URL="mysql://user:password@ogcore-database:3306/ogcore"
|
|
|
|
# JWT
|
|
JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
|
|
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
|
|
JWT_PASSPHRASE=<tu-passphrase>
|
|
|
|
# Mercure
|
|
MERCURE_URL=http://mercure:3000/.well-known/mercure
|
|
MERCURE_PUBLIC_URL=http://127.0.0.1:8080/.well-known/mercure
|
|
MERCURE_JWT_SECRET=<tu-secreto-mercure>
|
|
|
|
# Servicios externos
|
|
REMOTE_PC_URL=<url-uds>
|
|
REMOTE_PC_AUTH_LOGIN=<login>
|
|
REMOTE_PC_AUTH_USERNAME=<username>
|
|
REMOTE_PC_AUTH_PASSWORD=<password>
|
|
|
|
# SSL/TLS
|
|
SSL_ENABLED=false
|
|
```
|
|
|
|
#### 6.2.2 Configuración de CORS
|
|
|
|
Edita `config/packages/nelmio_cors.yaml` para configurar CORS según tus necesidades.
|
|
|
|
#### 6.2.3 Configuración de API Platform
|
|
|
|
La configuración de API Platform se encuentra en `config/packages/api_platform.yaml`.
|
|
|
|
### 6.3 Instalación en Producción
|
|
|
|
Para entornos de producción, utiliza el archivo `docker-compose-deploy.yml`:
|
|
|
|
```bash
|
|
docker compose -f docker-compose-deploy.yml up -d
|
|
```
|
|
|
|
Asegúrate de:
|
|
- Cambiar todas las contraseñas por defecto
|
|
- Configurar SSL/TLS
|
|
- Configurar backups automáticos de base de datos
|
|
- Configurar monitoreo y alertas
|
|
- Revisar los límites de recursos de Docker
|
|
|
|
---
|
|
|
|
## 7. Modelo de Datos
|
|
|
|
### 7.1 Diagrama de Entidades
|
|
|
|
El sistema cuenta con 35 entidades principales agrupadas en los siguientes dominios:
|
|
|
|
### 7.2 Entidades Principales
|
|
|
|
#### 7.2.1 Client (Cliente)
|
|
|
|
Representa un equipo físico en el sistema.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del cliente
|
|
- `serialNumber`: Número de serie
|
|
- `mac`: Dirección MAC (única)
|
|
- `ip`: Dirección IP (única)
|
|
- `status`: Estado del cliente (active, inactive, busy, windows, linux, etc.)
|
|
- `netiface`: Interfaz de red
|
|
- `netDriver`: Driver de red
|
|
- `validation`: Estado de validación
|
|
- `maintenance`: Modo mantenimiento
|
|
- `position`: Posición en el aula (x, y)
|
|
- `firmwareType`: Tipo de firmware (BIOS/UEFI)
|
|
- `agentJobId`: ID del trabajo del agente en ejecución
|
|
- `pxeSync`: Sincronización PXE
|
|
- `token`: Token de autenticación del cliente
|
|
|
|
**Relaciones:**
|
|
- `organizationalUnit`: Pertenece a una unidad organizativa (aula/grupo)
|
|
- `partitions`: Tiene múltiples particiones
|
|
- `menu`: Menú de arranque asignado
|
|
- `hardwareProfile`: Perfil de hardware asociado
|
|
- `template`: Plantilla PXE asignada
|
|
- `repository`: Repositorio de imágenes
|
|
- `subnet`: Subred a la que pertenece
|
|
- `ogLive`: Imagen Live asignada
|
|
|
|
#### 7.2.2 OrganizationalUnit (Unidad Organizativa)
|
|
|
|
Representa aulas o grupos de equipos.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre de la unidad
|
|
- `description`: Descripción
|
|
- `type`: Tipo (aula, grupo, etc.)
|
|
|
|
**Relaciones:**
|
|
- `parent`: Unidad organizativa padre (jerarquía)
|
|
- `children`: Unidades hijas
|
|
- `clients`: Clientes pertenecientes
|
|
- `networkSettings`: Configuración de red heredable
|
|
- `remoteCalendar`: Calendario remoto asociado
|
|
|
|
#### 7.2.3 Image (Imagen)
|
|
|
|
Representa una imagen de sistema operativo.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre de la imagen
|
|
- `description`: Descripción
|
|
- `type`: Tipo de imagen
|
|
- `size`: Tamaño en bytes
|
|
- `partition`: Partición de origen
|
|
- `status`: Estado (creating, success, failed, etc.)
|
|
- `isGlobal`: Imagen global compartida
|
|
- `isVirtual`: Imagen virtual
|
|
- `version`: Versión de la imagen
|
|
|
|
**Relaciones:**
|
|
- `operativeSystem`: Sistema operativo
|
|
- `softwareProfile`: Perfil de software
|
|
- `repositories`: Repositorios que contienen la imagen
|
|
- `originClient`: Cliente origen de la imagen
|
|
|
|
#### 7.2.4 Command (Comando)
|
|
|
|
Comandos ejecutables en el sistema.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del comando
|
|
- `description`: Descripción
|
|
- `script`: Script a ejecutar
|
|
|
|
**Relaciones:**
|
|
- `commandGroups`: Grupos de comandos a los que pertenece
|
|
|
|
#### 7.2.5 CommandTask (Tarea de Comando)
|
|
|
|
Tarea programada para ejecutar comandos.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `datetime`: Fecha y hora de ejecución
|
|
- `parameters`: Parámetros de ejecución
|
|
- `status`: Estado de la tarea
|
|
|
|
**Relaciones:**
|
|
- `commands`: Comandos a ejecutar
|
|
- `commandGroups`: Grupos de comandos
|
|
- `clients`: Clientes objetivo
|
|
- `schedule`: Programación recurrente
|
|
|
|
#### 7.2.6 Trace (Traza)
|
|
|
|
Registro de ejecución de comandos.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `command`: Nombre del comando ejecutado
|
|
- `input`: Parámetros de entrada
|
|
- `output`: Resultado de ejecución
|
|
- `status`: Estado (pending, processing, success, failed, cancelled)
|
|
- `executedAt`: Fecha de ejecución
|
|
- `finishedAt`: Fecha de finalización
|
|
- `cancelled`: Indica si fue cancelada
|
|
- `jobId`: ID del trabajo en el agente
|
|
|
|
**Relaciones:**
|
|
- `client`: Cliente donde se ejecutó
|
|
|
|
#### 7.2.7 HardwareProfile (Perfil de Hardware)
|
|
|
|
Inventario de hardware de un cliente.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `cpu`: Información de CPU
|
|
- `ram`: Memoria RAM
|
|
- `storage`: Almacenamiento
|
|
- `networkCards`: Tarjetas de red
|
|
|
|
**Relaciones:**
|
|
- `client`: Cliente asociado
|
|
- `hardwareTypes`: Tipos de hardware detectados
|
|
|
|
#### 7.2.8 SoftwareProfile (Perfil de Software)
|
|
|
|
Software instalado en una imagen.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del perfil
|
|
|
|
**Relaciones:**
|
|
- `software`: Software incluido
|
|
- `images`: Imágenes que usan este perfil
|
|
|
|
#### 7.2.9 ImageRepository (Repositorio de Imágenes)
|
|
|
|
Servidor de almacenamiento de imágenes.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del repositorio (único)
|
|
- `ip`: Dirección IP o DNS (único)
|
|
- `port`: Puerto
|
|
- `sshPort`: Puerto SSH
|
|
- `sshUser`: Usuario SSH
|
|
- `apiKey`: Clave API
|
|
- `status`: Estado del repositorio
|
|
|
|
**Relaciones:**
|
|
- `images`: Imágenes almacenadas
|
|
|
|
#### 7.2.10 Subnet (Subred)
|
|
|
|
Configuración de red.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre de la subred
|
|
- `cidr`: Notación CIDR
|
|
- `gateway`: Puerta de enlace
|
|
- `dns`: Servidores DNS
|
|
- `dhcpStart`: Inicio rango DHCP
|
|
- `dhcpEnd`: Fin rango DHCP
|
|
|
|
**Relaciones:**
|
|
- `clients`: Clientes en la subred
|
|
|
|
#### 7.2.11 Partition (Partición)
|
|
|
|
Partición de disco de un cliente.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `partitionNumber`: Número de partición
|
|
- `partitionType`: Tipo de partición
|
|
- `partitionSize`: Tamaño
|
|
- `partitionCode`: Código de partición
|
|
- `usedSize`: Tamaño usado
|
|
- `filesystem`: Sistema de archivos
|
|
|
|
**Relaciones:**
|
|
- `client`: Cliente propietario
|
|
- `image`: Imagen desplegada
|
|
- `operativeSystem`: Sistema operativo instalado
|
|
|
|
#### 7.2.12 PxeTemplate (Plantilla PXE)
|
|
|
|
Plantilla de arranque PXE.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre de la plantilla
|
|
- `content`: Contenido de la plantilla
|
|
- `default`: Plantilla por defecto
|
|
|
|
**Relaciones:**
|
|
- `clients`: Clientes que usan la plantilla
|
|
|
|
#### 7.2.13 RemoteCalendar (Calendario Remoto)
|
|
|
|
Integración con sistemas de reservas remotas.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del calendario
|
|
- `url`: URL del servicio
|
|
- `available`: Disponibilidad
|
|
|
|
**Relaciones:**
|
|
- `organizationalUnits`: Unidades organizativas asociadas
|
|
- `rules`: Reglas del calendario
|
|
|
|
#### 7.2.14 User (Usuario)
|
|
|
|
Usuario del sistema.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `username`: Nombre de usuario (único)
|
|
- `password`: Contraseña (hasheada)
|
|
- `email`: Correo electrónico
|
|
- `roles`: Roles del usuario
|
|
|
|
**Relaciones:**
|
|
- `userGroups`: Grupos de usuarios
|
|
- `view`: Vista preferida
|
|
|
|
#### 7.2.15 GitRepository (Repositorio Git)
|
|
|
|
Repositorio Git para versionado de imágenes.
|
|
|
|
**Campos principales:**
|
|
- `id`: UUID único
|
|
- `name`: Nombre del repositorio
|
|
- `url`: URL del repositorio
|
|
- `branch`: Rama
|
|
- `credentials`: Credenciales de acceso
|
|
|
|
### 7.3 Índices y Optimizaciones
|
|
|
|
La base de datos está optimizada con índices en:
|
|
- Campos de búsqueda frecuente (status, updatedAt)
|
|
- Campos únicos (IP, MAC, username)
|
|
- Claves foráneas
|
|
- Índices compuestos para consultas complejas
|
|
|
|
---
|
|
|
|
## 8. Componentes del Sistema
|
|
|
|
### 8.1 Controllers (Controladores)
|
|
|
|
El sistema cuenta con **102 controladores** organizados por dominio:
|
|
|
|
#### Controladores principales:
|
|
- **ClientController**: Gestión de clientes
|
|
- **ImageController**: Gestión de imágenes
|
|
- **OrganizationalUnitController**: Gestión de unidades organizativas
|
|
- **CommandController**: Gestión de comandos
|
|
- **TraceController**: Gestión de trazas
|
|
- **UserController**: Gestión de usuarios
|
|
- **SubnetController**: Gestión de subredes
|
|
- **RepositoryController**: Gestión de repositorios
|
|
|
|
### 8.2 States (Procesadores de Estado)
|
|
|
|
Los States implementan el patrón State de API Platform:
|
|
|
|
#### States principales (55 procesadores):
|
|
- **Providers**: Obtención de datos
|
|
- **Processors**: Procesamiento de escritura
|
|
- **Custom States**: Lógica personalizada
|
|
|
|
### 8.3 DTOs (Data Transfer Objects)
|
|
|
|
**93 DTOs** para transferencia de datos:
|
|
|
|
#### Tipos de DTOs:
|
|
- **Input DTOs**: Para recepción de datos
|
|
- **Output DTOs**: Para envío de datos
|
|
- **Transformation DTOs**: Para transformaciones
|
|
|
|
### 8.4 Validators (Validadores)
|
|
|
|
**18 validadores personalizados** para:
|
|
- Validación de IPs y MACs
|
|
- Validación de rangos DHCP
|
|
- Validación de particiones
|
|
- Validación de imágenes
|
|
- Validación de comandos
|
|
- Validación de usuarios
|
|
|
|
### 8.5 EventSubscribers (Suscriptores de Eventos)
|
|
|
|
**8 suscriptores** para:
|
|
- Publicación en Mercure al cambiar estados
|
|
- Limpieza de recursos
|
|
- Validaciones pre/post persistencia
|
|
- Logging de eventos
|
|
|
|
### 8.6 Factories (Fábricas)
|
|
|
|
**24 factories** para testing con Foundry:
|
|
- Creación de entidades para tests
|
|
- Datos de prueba realistas
|
|
- Estados predefinidos
|
|
|
|
---
|
|
|
|
## 9. API RESTful
|
|
|
|
### 9.1 Documentación
|
|
|
|
La API está completamente documentada con **OpenAPI 3.0** y accesible en:
|
|
|
|
```
|
|
http://127.0.0.1:8080/docs
|
|
```
|
|
|
|
### 9.2 Formato de Respuestas
|
|
|
|
#### Formato estándar (JSON-LD):
|
|
|
|
```json
|
|
{
|
|
"@context": "/contexts/Client",
|
|
"@id": "/clients/123e4567-e89b-12d3-a456-426614174000",
|
|
"@type": "Client",
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"name": "PC-01",
|
|
"mac": "00:11:22:33:44:55",
|
|
"ip": "192.168.1.100",
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
#### Formato alternativo (JSON):
|
|
|
|
```json
|
|
{
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"name": "PC-01",
|
|
"mac": "00:11:22:33:44:55",
|
|
"ip": "192.168.1.100",
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
### 9.3 Paginación
|
|
|
|
Todas las colecciones soportan paginación:
|
|
|
|
```
|
|
GET /clients?page=1&itemsPerPage=30
|
|
```
|
|
|
|
Respuesta:
|
|
|
|
```json
|
|
{
|
|
"@context": "/contexts/Client",
|
|
"@id": "/clients",
|
|
"@type": "hydra:Collection",
|
|
"hydra:member": [...],
|
|
"hydra:totalItems": 150,
|
|
"hydra:view": {
|
|
"@id": "/clients?page=1",
|
|
"@type": "hydra:PartialCollectionView",
|
|
"hydra:first": "/clients?page=1",
|
|
"hydra:last": "/clients?page=5",
|
|
"hydra:next": "/clients?page=2"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 9.4 Filtrado
|
|
|
|
Soporta filtros avanzados:
|
|
|
|
```
|
|
GET /clients?status=active
|
|
GET /clients?organizationalUnit.name=Aula1
|
|
GET /traces?client.id=123&status=pending
|
|
```
|
|
|
|
### 9.5 Ordenamiento
|
|
|
|
```
|
|
GET /clients?order[name]=asc
|
|
GET /traces?order[createdAt]=desc
|
|
```
|
|
|
|
### 9.6 Endpoints Principales
|
|
|
|
#### 9.6.1 Autenticación
|
|
|
|
```
|
|
POST /auth/login
|
|
POST /auth/refresh
|
|
```
|
|
|
|
#### 9.6.2 Clientes
|
|
|
|
```
|
|
GET /clients
|
|
POST /clients
|
|
GET /clients/{id}
|
|
PUT /clients/{id}
|
|
PATCH /clients/{id}
|
|
DELETE /clients/{id}
|
|
POST /clients/batch
|
|
POST /clients/{id}/power-on
|
|
POST /clients/{id}/power-off
|
|
POST /clients/{id}/reboot
|
|
```
|
|
|
|
#### 9.6.3 Imágenes
|
|
|
|
```
|
|
GET /images
|
|
POST /images
|
|
GET /images/{id}
|
|
PUT /images/{id}
|
|
DELETE /images/{id}
|
|
POST /images/{id}/deploy
|
|
POST /images/{id}/create
|
|
POST /images/{id}/backup
|
|
```
|
|
|
|
#### 9.6.4 Comandos y Tareas
|
|
|
|
```
|
|
GET /commands
|
|
POST /commands
|
|
GET /command-tasks
|
|
POST /command-tasks
|
|
PUT /command-tasks/{id}
|
|
DELETE /command-tasks/{id}
|
|
```
|
|
|
|
#### 9.6.5 Trazas
|
|
|
|
```
|
|
GET /traces
|
|
GET /traces/{id}
|
|
PUT /traces/{id}
|
|
PATCH /traces/{id}/complete
|
|
PATCH /traces/{id}/cancel
|
|
```
|
|
|
|
### 9.7 Códigos de Estado HTTP
|
|
|
|
| Código | Significado |
|
|
|--------|-------------|
|
|
| 200 | OK - Operación exitosa |
|
|
| 201 | Created - Recurso creado |
|
|
| 204 | No Content - Eliminación exitosa |
|
|
| 400 | Bad Request - Datos inválidos |
|
|
| 401 | Unauthorized - No autenticado |
|
|
| 403 | Forbidden - Sin permisos |
|
|
| 404 | Not Found - Recurso no encontrado |
|
|
| 409 | Conflict - Conflicto (cliente ocupado, constraint violation) |
|
|
| 422 | Unprocessable Entity - Validación fallida |
|
|
| 500 | Internal Server Error - Error del servidor |
|
|
|
|
---
|
|
|
|
## 10. Seguridad y Autenticación
|
|
|
|
### 10.1 Sistema de Autenticación JWT
|
|
|
|
ogCore utiliza **JSON Web Tokens (JWT)** para autenticación:
|
|
|
|
#### 10.1.1 Obtener Token
|
|
|
|
```bash
|
|
POST /auth/login
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"username": "admin",
|
|
"password": "password"
|
|
}
|
|
```
|
|
|
|
Respuesta:
|
|
|
|
```json
|
|
{
|
|
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"refresh_token": "def50200a54b7b..."
|
|
}
|
|
```
|
|
|
|
#### 10.1.2 Usar Token
|
|
|
|
Incluir el token en el header `Authorization`:
|
|
|
|
```bash
|
|
GET /clients
|
|
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
|
|
```
|
|
|
|
#### 10.1.3 Refresh Token
|
|
|
|
```bash
|
|
POST /auth/refresh
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"refresh_token": "def50200a54b7b..."
|
|
}
|
|
```
|
|
|
|
### 10.2 Control de Acceso
|
|
|
|
#### Rutas Públicas:
|
|
- `/auth/login`
|
|
- `/auth/refresh`
|
|
- `/docs`
|
|
- `/opengnsys/rest/*` (webhooks)
|
|
- `/og-repository/webhook`
|
|
- `/menu-browser`
|
|
|
|
#### Rutas Protegidas:
|
|
- Todo lo demás requiere `IS_AUTHENTICATED_FULLY`
|
|
|
|
### 10.3 Roles de Usuario
|
|
|
|
Los roles se gestionan en la entidad `User`:
|
|
|
|
```php
|
|
$user->setRoles(['ROLE_USER']);
|
|
$user->setRoles(['ROLE_ADMIN']);
|
|
```
|
|
|
|
### 10.4 Seguridad de Contraseñas
|
|
|
|
- Hashing con **bcrypt** automático
|
|
- Validación de fortaleza
|
|
- Cambio de contraseña seguro
|
|
|
|
### 10.5 CORS (Cross-Origin Resource Sharing)
|
|
|
|
Configurado en `nelmio_cors.yaml` para permitir acceso desde frontend.
|
|
|
|
### 10.6 SSL/TLS
|
|
|
|
Para producción, habilitar SSL:
|
|
|
|
```bash
|
|
SSL_ENABLED=true
|
|
```
|
|
|
|
Configurar certificados en `/certs/`.
|
|
|
|
---
|
|
|
|
## 11. Servicios Principales
|
|
|
|
### 11.1 CreatePartitionService
|
|
|
|
**Propósito**: Crear y actualizar particiones de clientes.
|
|
|
|
**Funcionalidad**:
|
|
- Recibe información de particiones del agente
|
|
- Crea/actualiza particiones en base de datos
|
|
- Detecta tipo de firmware (BIOS/UEFI)
|
|
- Calcula códigos de partición
|
|
|
|
### 11.2 CreateTraceService
|
|
|
|
**Propósito**: Crear trazas de ejecución para tareas programadas.
|
|
|
|
**Funcionalidad**:
|
|
- Genera trazas para cada combinación cliente-comando
|
|
- Gestiona comandos agrupados
|
|
- Establece estado inicial y fecha de ejecución
|
|
|
|
### 11.3 ChangeClientNetworkSettingsService
|
|
|
|
**Propósito**: Cambiar configuración de red de clientes.
|
|
|
|
**Funcionalidad**:
|
|
- Actualiza subnet, IP, configuración de red
|
|
- Sincroniza con servicios externos (DHCP)
|
|
|
|
### 11.4 ExternalGitRepositoryService
|
|
|
|
**Propósito**: Gestión de repositorios Git para imágenes.
|
|
|
|
**Funcionalidad**:
|
|
- Backup de imágenes a Git
|
|
- Versionado de imágenes
|
|
- Sincronización con repositorios remotos
|
|
|
|
### 11.5 StatusService (OgBoot/OgDhcp/OgRepository)
|
|
|
|
**Propósito**: Verificar estado de servicios externos.
|
|
|
|
**Funcionalidad**:
|
|
- Health checks de servicios
|
|
- Manejo de errores de conexión
|
|
- Logging de estado
|
|
|
|
### 11.6 UDSClient
|
|
|
|
**Propósito**: Integración con UDS (Universal Desktop Services).
|
|
|
|
**Funcionalidad**:
|
|
- Autenticación con UDS
|
|
- Obtención de service pools
|
|
- Cálculo de asientos disponibles
|
|
- Gestión de calendarios remotos
|
|
|
|
### 11.7 Trace/CreateService
|
|
|
|
**Propósito**: Servicio especializado para creación de trazas.
|
|
|
|
**Funcionalidad**:
|
|
- Validación de parámetros de entrada
|
|
- Creación de trazas individuales o masivas
|
|
|
|
### 11.8 Utils/GetPartitionCodeService
|
|
|
|
**Propósito**: Obtener código de partición según tipo y filesystem.
|
|
|
|
### 11.9 Utils/SimplifyOgLiveFilenameService
|
|
|
|
**Propósito**: Simplificar nombres de archivos OgLive para mostrar al usuario.
|
|
|
|
### 11.10 Utils/GetIpAddressAndNetmaskFromCIDRService
|
|
|
|
**Propósito**: Convertir notación CIDR a IP y máscara de red.
|
|
|
|
---
|
|
|
|
## 12. Comandos de Consola
|
|
|
|
ogCore incluye **18 comandos de consola** para tareas administrativas:
|
|
|
|
### 12.1 Comandos de Inicialización
|
|
|
|
#### 12.1.1 Cargar Grupos de Usuario por Defecto
|
|
|
|
```bash
|
|
php bin/console app:load-default-user-groups
|
|
```
|
|
|
|
Crea los grupos de usuarios predeterminados del sistema.
|
|
|
|
#### 12.1.2 Cargar Comandos por Defecto
|
|
|
|
```bash
|
|
php bin/console app:load-default-commands
|
|
```
|
|
|
|
Carga los comandos básicos del sistema.
|
|
|
|
#### 12.1.3 Cargar Usuario Admin
|
|
|
|
```bash
|
|
php bin/console app:load-default-user-admin
|
|
```
|
|
|
|
Crea el usuario administrador por defecto.
|
|
|
|
#### 12.1.4 Cargar Menú por Defecto
|
|
|
|
```bash
|
|
php bin/console app:load-default-menu
|
|
```
|
|
|
|
Carga menús de arranque predeterminados.
|
|
|
|
#### 12.1.5 Cargar Tipos de Hardware
|
|
|
|
```bash
|
|
php bin/console app:load-hardware-types
|
|
```
|
|
|
|
Inicializa la tabla de tipos de hardware.
|
|
|
|
#### 12.1.6 Cargar Unidad Organizativa por Defecto
|
|
|
|
```bash
|
|
php bin/console app:load-organizational-unit-default
|
|
```
|
|
|
|
Crea la unidad organizativa raíz.
|
|
|
|
### 12.2 Comandos de Operación
|
|
|
|
#### 12.2.1 Verificar Disponibilidad de Clientes
|
|
|
|
```bash
|
|
php bin/console app:check-client-availability
|
|
```
|
|
|
|
**Ejecución**: Cada 1 minuto (cron)
|
|
|
|
Verifica el estado de conectividad de los clientes y actualiza su estado si no responden en un tiempo determinado.
|
|
|
|
#### 12.2.2 Ejecutar Trazas Pendientes
|
|
|
|
```bash
|
|
php bin/console app:execute-pending-traces
|
|
```
|
|
|
|
**Ejecución**: Cada 1 minuto (cron)
|
|
|
|
Procesa las trazas en estado `PENDING` y las ejecuta en los clientes correspondientes.
|
|
|
|
#### 12.2.3 Ejecutar Tareas Programadas
|
|
|
|
```bash
|
|
php bin/console app:run-scheduled-command-tasks
|
|
```
|
|
|
|
**Ejecución**: Cada 1 minuto (cron)
|
|
|
|
Ejecuta tareas programadas que han llegado a su hora de ejecución.
|
|
|
|
### 12.3 Comandos de Migración
|
|
|
|
Comandos para migrar datos desde OpenGnsys 1.1:
|
|
|
|
#### 12.3.1 Migrar Unidades Organizativas
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:organizational-unit
|
|
```
|
|
|
|
#### 12.3.2 Migrar Perfiles de Hardware
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:hardware-profile
|
|
```
|
|
|
|
#### 12.3.3 Migrar Clientes
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:clients
|
|
```
|
|
|
|
#### 12.3.4 Migrar Sistemas Operativos
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:os
|
|
```
|
|
|
|
#### 12.3.5 Migrar Imágenes
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:image
|
|
```
|
|
|
|
#### 12.3.6 Migrar Perfiles de Software
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:software-profile
|
|
```
|
|
|
|
#### 12.3.7 Migrar Particiones de Clientes
|
|
|
|
```bash
|
|
php bin/console opengnsys:migration:partition-client
|
|
```
|
|
|
|
### 12.4 Comandos de Desarrollo
|
|
|
|
#### 12.4.1 Crear Repositorios de Imágenes
|
|
|
|
```bash
|
|
php bin/console app:create-image-repositories
|
|
```
|
|
|
|
Crea repositorios de imágenes para desarrollo/testing.
|
|
|
|
#### 12.4.2 Cargar Trazas de Ejemplo
|
|
|
|
```bash
|
|
php bin/console app:charge-example-trace
|
|
```
|
|
|
|
Carga trazas de ejemplo para testing.
|
|
|
|
### 12.5 Configuración de Cron
|
|
|
|
Agregar al crontab:
|
|
|
|
```bash
|
|
* * * * * docker exec ogcore-php php bin/console app:check-client-availability
|
|
* * * * * docker exec ogcore-php php bin/console app:execute-pending-traces
|
|
* * * * * docker exec ogcore-php php bin/console app:run-scheduled-command-tasks
|
|
```
|
|
|
|
---
|
|
|
|
## 13. Migraciones de Datos
|
|
|
|
### 13.1 Sistema de Migraciones de Doctrine
|
|
|
|
ogCore utiliza Doctrine Migrations para gestionar cambios en el esquema de base de datos.
|
|
|
|
#### 13.1.1 Crear una Migración
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console make:migration
|
|
```
|
|
|
|
#### 13.1.2 Ejecutar Migraciones
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console doctrine:migrations:migrate
|
|
```
|
|
|
|
#### 13.1.3 Ver Estado de Migraciones
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console doctrine:migrations:status
|
|
```
|
|
|
|
#### 13.1.4 Revertir Migración
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console doctrine:migrations:migrate prev
|
|
```
|
|
|
|
### 13.2 Migración desde OpenGnsys 1.1
|
|
|
|
Para migrar datos desde una instalación de OpenGnsys 1.1:
|
|
|
|
#### 13.2.1 Crear Base de Datos Temporal
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console doctrine:database:create --connection=og_1
|
|
```
|
|
|
|
#### 13.2.2 Cargar Dump de OpenGnsys 1.1
|
|
|
|
```bash
|
|
docker exec -i ogcore-database mysql -u user -p ogcore_old_og < dump_og_1.1.sql
|
|
```
|
|
|
|
#### 13.2.3 Ejecutar Migraciones
|
|
|
|
Ejecutar los comandos de migración en orden:
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console opengnsys:migration:organizational-unit
|
|
docker exec ogcore-php php bin/console opengnsys:migration:hardware-profile
|
|
docker exec ogcore-php php bin/console opengnsys:migration:clients
|
|
docker exec ogcore-php php bin/console opengnsys:migration:os
|
|
docker exec ogcore-php php bin/console opengnsys:migration:image
|
|
docker exec ogcore-php php bin/console opengnsys:migration:software-profile
|
|
```
|
|
|
|
### 13.3 Backup y Restauración
|
|
|
|
#### 13.3.1 Backup de Base de Datos
|
|
|
|
```bash
|
|
docker exec ogcore-database mysqldump -u user -p ogcore > backup_$(date +%Y%m%d).sql
|
|
```
|
|
|
|
#### 13.3.2 Restaurar Base de Datos
|
|
|
|
```bash
|
|
docker exec -i ogcore-database mysql -u user -p ogcore < backup_20251008.sql
|
|
```
|
|
|
|
---
|
|
|
|
## 14. Testing
|
|
|
|
### 14.1 Framework de Testing
|
|
|
|
ogCore utiliza **PHPUnit** con integración de Symfony y Doctrine.
|
|
|
|
### 14.2 Ejecutar Tests
|
|
|
|
#### 14.2.1 Todos los Tests
|
|
|
|
```bash
|
|
docker compose exec php bin/phpunit
|
|
```
|
|
|
|
#### 14.2.2 Tests Específicos
|
|
|
|
```bash
|
|
docker compose exec php bin/phpunit tests/Functional/ClientTest.php
|
|
```
|
|
|
|
#### 14.2.3 Tests con Coverage
|
|
|
|
```bash
|
|
docker compose exec php bin/phpunit --coverage-html coverage/
|
|
```
|
|
|
|
### 14.3 Tipos de Tests
|
|
|
|
#### 14.3.1 Tests Funcionales
|
|
|
|
Ubicación: `tests/Functional/`
|
|
|
|
20 archivos de tests funcionales que prueban:
|
|
- Endpoints de API
|
|
- Flujos completos
|
|
- Integraciones
|
|
|
|
Ejemplo:
|
|
|
|
```php
|
|
public function testCreateClient(): void
|
|
{
|
|
$client = static::createClient();
|
|
$client->request('POST', '/clients', [
|
|
'json' => [
|
|
'name' => 'Test Client',
|
|
'mac' => '00:11:22:33:44:55',
|
|
'ip' => '192.168.1.100'
|
|
]
|
|
]);
|
|
|
|
$this->assertResponseStatusCodeSame(201);
|
|
}
|
|
```
|
|
|
|
### 14.4 Factories para Testing
|
|
|
|
Se utilizan **Zenstruck Foundry** factories (24 factories) para crear datos de prueba:
|
|
|
|
```php
|
|
ClientFactory::createOne([
|
|
'name' => 'Test PC',
|
|
'status' => 'active'
|
|
]);
|
|
```
|
|
|
|
### 14.5 Base de Datos de Testing
|
|
|
|
Los tests utilizan **DAMA Doctrine Test Bundle** para:
|
|
- Ejecutar cada test en una transacción
|
|
- Rollback automático después de cada test
|
|
- Aislamiento completo entre tests
|
|
|
|
---
|
|
|
|
## 15. Despliegue
|
|
|
|
### 15.1 Despliegue con Docker Compose
|
|
|
|
#### 15.1.1 Desarrollo
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
#### 15.1.2 Producción
|
|
|
|
```bash
|
|
docker compose -f docker-compose-deploy.yml up -d
|
|
```
|
|
|
|
### 15.2 Despliegue con Jenkins
|
|
|
|
El proyecto incluye **Jenkinsfile** para CI/CD.
|
|
|
|
#### Pipeline stages:
|
|
1. **Checkout**: Clonar repositorio
|
|
2. **Build**: Construir imagen Docker
|
|
3. **Test**: Ejecutar tests
|
|
4. **Package**: Crear paquete Debian
|
|
5. **Deploy**: Desplegar en servidor
|
|
|
|
### 15.3 Paquete Debian
|
|
|
|
El proyecto puede empaquetarse como `.deb`:
|
|
|
|
```bash
|
|
./package.sh
|
|
```
|
|
|
|
Estructura del paquete en `debian/`:
|
|
- Control files
|
|
- Postinst/preinst scripts
|
|
- Systemd service file
|
|
- Configuración
|
|
|
|
### 15.4 Configuración de Producción
|
|
|
|
#### 15.4.1 Variables de Entorno
|
|
|
|
Crear `.env.local` con configuración de producción:
|
|
|
|
```bash
|
|
APP_ENV=prod
|
|
APP_DEBUG=0
|
|
DATABASE_URL="mysql://user:pass@localhost:3306/ogcore"
|
|
# ... más configuración
|
|
```
|
|
|
|
#### 15.4.2 Optimizaciones
|
|
|
|
```bash
|
|
# Limpiar caché
|
|
docker exec ogcore-php php bin/console cache:clear --env=prod
|
|
|
|
# Calentar caché
|
|
docker exec ogcore-php php bin/console cache:warmup --env=prod
|
|
|
|
# Optimizar autoloader
|
|
docker exec ogcore-php composer dump-autoload --optimize --classmap-authoritative
|
|
```
|
|
|
|
### 15.5 Monitoreo
|
|
|
|
#### 15.5.1 Logs
|
|
|
|
Logs ubicados en `var/log/`:
|
|
- `dev.log` / `prod.log`: Logs de aplicación
|
|
- `nginx/access.log`: Accesos a nginx
|
|
- `nginx/error.log`: Errores de nginx
|
|
|
|
#### 15.5.2 Syslog
|
|
|
|
Los logs también se envían a syslog para centralización.
|
|
|
|
### 15.6 Escalabilidad
|
|
|
|
Para escalar horizontalmente:
|
|
|
|
1. **Base de datos**: Usar MariaDB con replicación master-slave
|
|
2. **PHP**: Aumentar réplicas de contenedor PHP
|
|
3. **Load Balancer**: Usar nginx como balanceador de carga
|
|
4. **Caché**: Implementar Redis para sesiones y caché
|
|
5. **Mercure**: Escalar hub de Mercure
|
|
|
|
---
|
|
|
|
## 16. Mantenimiento y Operaciones
|
|
|
|
### 16.1 Reiniciar Base de Datos
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console doctrine:database:drop --force
|
|
docker exec ogcore-php php bin/console doctrine:database:create
|
|
docker exec ogcore-php php bin/console doctrine:migrations:migrate --no-interaction
|
|
docker exec ogcore-php php bin/console doctrine:fixtures:load --no-interaction
|
|
```
|
|
|
|
### 16.2 Limpiar Caché
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console cache:clear
|
|
docker exec ogcore-php php bin/console cache:warmup
|
|
```
|
|
|
|
### 16.3 Actualizar Dependencias
|
|
|
|
```bash
|
|
docker exec ogcore-php composer update
|
|
```
|
|
|
|
### 16.4 Regenerar Claves JWT
|
|
|
|
```bash
|
|
docker exec ogcore-php php bin/console lexik:jwt:generate-keypair --overwrite
|
|
```
|
|
|
|
### 16.5 Backups Automáticos
|
|
|
|
Script ejemplo para backup automático:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
DATE=$(date +%Y%m%d_%H%M%S)
|
|
BACKUP_DIR="/backups"
|
|
|
|
# Backup de base de datos
|
|
docker exec ogcore-database mysqldump -u user -p password ogcore > $BACKUP_DIR/db_$DATE.sql
|
|
|
|
# Backup de archivos
|
|
tar -czf $BACKUP_DIR/files_$DATE.tar.gz /var/www/html/ogcore/var
|
|
|
|
# Limpiar backups antiguos (>30 días)
|
|
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
|
|
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
|
|
```
|
|
|
|
### 16.6 Monitoreo de Salud
|
|
|
|
#### Health Check Endpoint
|
|
|
|
```bash
|
|
GET /health
|
|
```
|
|
|
|
#### Verificar Estado de Servicios
|
|
|
|
```bash
|
|
# PHP
|
|
docker exec ogcore-php php -v
|
|
|
|
# Nginx
|
|
docker exec ogcore-nginx nginx -t
|
|
|
|
# MariaDB
|
|
docker exec ogcore-database mysqladmin -u user -p status
|
|
```
|
|
|
|
### 16.7 Rotación de Logs
|
|
|
|
Configurar logrotate:
|
|
|
|
```bash
|
|
/var/www/html/ogcore/var/log/*.log {
|
|
daily
|
|
rotate 14
|
|
compress
|
|
delaycompress
|
|
notifempty
|
|
create 0640 www-data www-data
|
|
sharedscripts
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 17. Integración con Otros Servicios
|
|
|
|
### 17.1 ogRepository
|
|
|
|
**Propósito**: Gestión de repositorios de imágenes.
|
|
|
|
**Endpoints integrados**:
|
|
- Crear imagen
|
|
- Desplegar imagen
|
|
- Backup imagen
|
|
- Eliminar imagen
|
|
- Convertir a imagen virtual
|
|
- Importar imagen externa
|
|
- Verificar integridad
|
|
- Imagen global
|
|
|
|
**Webhook**: `/og-repository/webhook`
|
|
|
|
### 17.2 ogDhcp
|
|
|
|
**Propósito**: Gestión de DHCP dinámico.
|
|
|
|
**Funcionalidades**:
|
|
- Agregar clientes a DHCP
|
|
- Eliminar clientes de DHCP
|
|
- Actualizar configuración
|
|
- Gestión de subredes
|
|
|
|
### 17.3 ogBoot
|
|
|
|
**Propósito**: Gestión de archivos de arranque PXE.
|
|
|
|
**Funcionalidades**:
|
|
- Crear archivos de arranque
|
|
- Actualizar plantillas PXE
|
|
- Eliminar configuraciones
|
|
- Sincronización de menús
|
|
|
|
### 17.4 ogAgent
|
|
|
|
**Propósito**: Agente instalado en clientes para ejecutar comandos.
|
|
|
|
**Operaciones**:
|
|
- Power on/off/reboot
|
|
- Crear/desplegar imágenes
|
|
- Particionar discos
|
|
- Ejecutar scripts
|
|
- Obtener inventario hardware
|
|
- Verificar tamaño de particiones
|
|
- Kill jobs
|
|
|
|
### 17.5 UDS (Universal Desktop Services)
|
|
|
|
**Propósito**: Integración con sistema de escritorios remotos.
|
|
|
|
**Funcionalidades**:
|
|
- Autenticación
|
|
- Obtener service pools
|
|
- Calcular disponibilidad
|
|
- Gestión de reservas
|
|
|
|
### 17.6 Git (Versionado de Imágenes)
|
|
|
|
**Propósito**: Versionado de imágenes con Git.
|
|
|
|
**Funcionalidades**:
|
|
- Backup a repositorio Git
|
|
- Versionado automático
|
|
- Recuperación de versiones
|
|
- Sincronización
|
|
|
|
### 17.7 Mercure (Notificaciones en Tiempo Real)
|
|
|
|
**Propósito**: Notificaciones push en tiempo real.
|
|
|
|
**Eventos publicados**:
|
|
- Cambio de estado de clientes
|
|
- Actualización de trazas
|
|
- Cambios en comandos
|
|
- Alertas y notificaciones
|
|
|
|
**Suscripción del cliente**:
|
|
|
|
```javascript
|
|
const eventSource = new EventSource('http://localhost:8080/.well-known/mercure?topic=/clients/{id}');
|
|
eventSource.onmessage = event => {
|
|
const data = JSON.parse(event.data);
|
|
console.log('Client updated:', data);
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 18. Roadmap y Changelog
|
|
|
|
### 18.1 Versión Actual: 0.5.0
|
|
|
|
### 18.2 Últimas Características (v0.25.1 - Octubre 2025)
|
|
|
|
- **Tareas programadas**: Sistema completo de colas y scheduling
|
|
- **Inventario hardware**: Obtención automática de inventario
|
|
- **Clonado de imágenes**: Mejoras en el servicio de clonado
|
|
- **Repositorios Git**: Backup y gestión de repositorios
|
|
- **Particionado**: Integración con agente para scripts de particionado
|
|
- **Gestión de trazas**: Marcar como completadas, cancelación
|
|
- **Estados de cliente**: Nuevo estado "enviado" para Windows/Linux
|
|
- **Validación de particiones**: Comprobación de tamaños
|
|
- **Imagen versionada**: Sistema de versionado de imágenes
|
|
- **Calendario remoto**: Integración con UDS
|
|
- **Mercure**: Notificaciones en tiempo real
|
|
- **Despliegue multicast**: Modos torrent y UDPCAST
|
|
|
|
### 18.3 Próximas Características (Roadmap)
|
|
|
|
#### v0.6.0 (Q4 2025)
|
|
- [ ] Dashboard de administración mejorado
|
|
- [ ] Reportes y estadísticas avanzadas
|
|
- [ ] API GraphQL complementaria
|
|
- [ ] Mejoras en rendimiento de queries
|
|
|
|
#### v0.7.0 (Q1 2026)
|
|
- [ ] Soporte para múltiples lenguajes (i18n completo)
|
|
- [ ] Sistema de plugins
|
|
- [ ] Mejoras en clustering
|
|
- [ ] API de webhooks salientes
|
|
|
|
#### v1.0.0 (Q2 2026)
|
|
- [ ] Versión estable de producción
|
|
- [ ] Documentación completa de API
|
|
- [ ] Guías de migración finalizadas
|
|
- [ ] Certificación de seguridad
|
|
|
|
### 18.4 Changelog Resumido
|
|
|
|
Ver `CHANGELOG.md` para el historial completo de cambios.
|
|
|
|
**Versiones destacadas**:
|
|
|
|
- **0.25.1** (2025-10-01): Correcciones en tareas programadas
|
|
- **0.25.0** (2025-09-23): Inventario hardware
|
|
- **0.24.0** (2025-09-09): Servicio de eliminación de repositorios Git
|
|
- **0.23.0** (2025-09-08): Backups a repositorios Git
|
|
- **0.20.0** (2025-08-25): Sistema de colas y tareas
|
|
- **0.15.0** (2025-06-26): Integración ogGit y sistema de cola
|
|
- **0.14.0** (2025-06-02): Mover equipos, imagen cache, inicio sesión
|
|
- **0.13.0** (2025-05-20): Comunicación TLS con agente
|
|
- **0.12.0** (2025-05-13): Tareas programadas, integración ogGit
|
|
- **0.11.0** (2025-04-11): Versionado de imágenes, ejecución de scripts
|
|
- **0.10.0** (2025-03-25): Imagen virtual, importar imágenes
|
|
- **0.9.0** (2025-03-04): Mercure, notificaciones en tiempo real
|
|
- **0.8.0** (2025-01-10): Imagen global, jerarquía de aulas
|
|
- **0.7.3** (2025-01-03): Multiselección, import/export, torrent/udpcast
|
|
|
|
---
|
|
|
|
## 19. Contribución
|
|
|
|
### 19.1 Guía de Contribución
|
|
|
|
Para contribuir al proyecto:
|
|
|
|
1. **Fork** el repositorio
|
|
2. Crea una **rama** para tu feature: `git checkout -b feature/nueva-funcionalidad`
|
|
3. **Commit** tus cambios: `git commit -am 'Añade nueva funcionalidad'`
|
|
4. **Push** a la rama: `git push origin feature/nueva-funcionalidad`
|
|
5. Crea un **Pull Request**
|
|
|
|
### 19.2 Estándares de Código
|
|
|
|
- Seguir **PSR-12** para PHP
|
|
- Usar **Type Hints** en PHP 8.3
|
|
- Documentar con **PHPDoc**
|
|
- Tests para nuevas funcionalidades
|
|
- Commits descriptivos en español
|
|
|
|
### 19.3 Proceso de Revisión
|
|
|
|
1. CI/CD ejecuta tests automáticamente
|
|
2. Revisión de código por maintainers
|
|
3. Aprobación requerida antes de merge
|
|
4. Merge a rama develop
|
|
5. Release periódicos a main
|
|
|
|
### 19.4 Reportar Bugs
|
|
|
|
Usar el sistema de Issues del repositorio:
|
|
|
|
**Template de Bug**:
|
|
```
|
|
**Descripción del bug**
|
|
Descripción clara y concisa del bug.
|
|
|
|
**Pasos para reproducir**
|
|
1. Ir a '...'
|
|
2. Hacer clic en '...'
|
|
3. Ver error
|
|
|
|
**Comportamiento esperado**
|
|
Lo que esperabas que sucediera.
|
|
|
|
**Screenshots**
|
|
Si aplica, añadir screenshots.
|
|
|
|
**Entorno**
|
|
- OS: [ej. Ubuntu 22.04]
|
|
- Versión: [ej. 0.5.0]
|
|
- Browser: [ej. Firefox 118]
|
|
```
|
|
|
|
---
|
|
|
|
## 20. Soporte y Contacto
|
|
|
|
### 20.1 Documentación Adicional
|
|
|
|
- **API Docs**: http://localhost:8080/docs
|
|
- **Postman Collection**: `swagger-assets/ogCore.postman_collection.zip`
|
|
- **Diagramas**: `swagger-assets/img_bbdd.png`
|
|
|
|
### 20.2 Recursos
|
|
|
|
- **Repositorio**: [URL del repositorio]
|
|
- **Wiki**: [URL de la wiki]
|
|
- **Issues**: [URL de issues]
|
|
|
|
### 20.3 Equipo de Desarrollo
|
|
|
|
Proyecto desarrollado por el equipo de OpenGnsys en colaboración con universidades participantes.
|
|
|
|
### 20.4 Licencia
|
|
|
|
Proyecto propietario. Ver archivo `LICENSE` para más información.
|
|
|
|
---
|
|
|
|
## Apéndices
|
|
|
|
### Apéndice A: Glosario de Términos
|
|
|
|
- **Cliente**: Equipo físico gestionado por el sistema
|
|
- **Imagen**: Copia bit a bit de una partición de disco
|
|
- **Traza**: Registro de ejecución de un comando
|
|
- **Unidad Organizativa**: Agrupación lógica de clientes (aula, grupo)
|
|
- **PXE**: Preboot Execution Environment, arranque por red
|
|
- **ogLive**: Imagen Live de arranque de OpenGnsys
|
|
- **Partición**: División lógica de un disco duro
|
|
- **Repositorio**: Servidor de almacenamiento de imágenes
|
|
|
|
### Apéndice B: Puertos y Servicios
|
|
|
|
| Puerto | Servicio | Protocolo | Descripción |
|
|
|--------|----------|-----------|-------------|
|
|
| 8080 | nginx | HTTP | API y docs |
|
|
| 3306 | MariaDB | MySQL | Base de datos |
|
|
| 9000 | PHP-FPM | FastCGI | Procesador PHP |
|
|
| 3000 | Mercure | HTTP/SSE | Notificaciones |
|
|
|
|
### Apéndice C: Estructura de Directorios
|
|
|
|
```
|
|
ogcore/
|
|
|-- bin/ # Ejecutables (console, phpunit)
|
|
|-- config/ # Configuración de Symfony
|
|
| |-- api_platform/ # Configuración de entidades API
|
|
| |-- packages/ # Configuración de bundles
|
|
| +-- routes/ # Rutas
|
|
|-- migrations/ # Migraciones de base de datos
|
|
|-- public/ # Punto de entrada web
|
|
|-- src/ # Código fuente
|
|
| |-- Command/ # Comandos de consola
|
|
| |-- Controller/ # Controladores
|
|
| |-- Dto/ # Data Transfer Objects
|
|
| |-- Entity/ # Entidades Doctrine
|
|
| |-- EventListener/# Event Listeners
|
|
| |-- EventSubscriber/ # Event Subscribers
|
|
| |-- Factory/ # Factories para testing
|
|
| |-- Filter/ # Filtros de API Platform
|
|
| |-- Repository/ # Repositorios Doctrine
|
|
| |-- Security/ # Seguridad y autenticación
|
|
| |-- Service/ # Servicios de negocio
|
|
| |-- State/ # States de API Platform
|
|
| +-- Validator/ # Validadores personalizados
|
|
|-- tests/ # Tests
|
|
|-- translations/ # Traducciones
|
|
|-- var/ # Archivos variables (cache, logs)
|
|
+-- vendor/ # Dependencias
|
|
|
|
```
|
|
|
|
### Apéndice D: Variables de Entorno Completas
|
|
|
|
Ver archivo `.env` para todas las variables de entorno disponibles.
|
|
|
|
---
|
|
|
|
**Fecha de actualización**: Octubre 2025
|
|
**Versión del documento**: 1.0
|
|
**Mantenedor**: Equipo OpenGnsys
|