ogCore sigue una arquitectura de microservicios basada en el patrón API-First:
-┌─────────────────────────────────────────────────────────────┐
-│ Frontend (Web UI) │
-└────────────────────────┬────────────────────────────────────┘
- │
- │ HTTP/REST
- │
-┌────────────────────────▼────────────────────────────────────┐
-│ ogCore API (Symfony) │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Controllers │ States │ DTOs │ Validators │ Filters │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Business Logic (Services) │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ Entities │ Repositories │ Doctrine ORM │ │
-│ └──────────────────────────────────────────────────────┘ │
-└────────────────────┬───────────────┬───────────────────────┘
- │ │
- ┌───────────▼──┐ ┌──────▼──────┐
- │ MariaDB │ │ Mercure │
- │ Database │ │ (WebSocket)│
- └──────────────┘ └─────────────┘
++-------------------------------------------------------------+
+| 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 │
-└──────────────┴──────────────┴──────────────┴────────────────┘
++-------------------------------------------------------------+
+| Servicios Externos Integrados |
++--------------+--------------+--------------+----------------+
+| ogRepository | ogDhcp | ogBoot | UDS/Git |
++--------------+--------------+--------------+----------------+El sistema cuenta con 35 entidades principales agrupadas en los -siguientes dominios:
-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
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
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
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
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
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ó
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
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
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
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
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
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
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
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
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
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
-El sistema cuenta con 102 controladores organizados por dominio:
-Los States implementan el patrón State de API Platform:
-93 DTOs para transferencia de datos:
-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 suscriptores para: - Publicación en Mercure al cambiar estados - Limpieza de recursos - Validaciones pre/post persistencia - Logging de eventos
-24 factories para testing con Foundry: - Creación de entidades para tests - Datos de prueba realistas - Estados predefinidos
La API está completamente documentada con OpenAPI 3.0 y accesible en:
http://127.0.0.1:8080/docsTodas las colecciones soportan paginación:
GET /clients?page=1&itemsPerPage=30Respuesta:
@@ -1416,25 +1205,25 @@ class="sourceCode json"> "hydra:next": "/clients?page=2"
}
}
-Soporta filtros avanzados:
GET /clients?status=active
GET /clients?organizationalUnit.name=Aula1
GET /traces?client.id=123&status=pendingGET /clients?order[name]=asc
GET /traces?order[createdAt]=descPOST /auth/login
POST /auth/refreshGET /clients
POST /clients
GET /clients/{id}
@@ -1445,8 +1234,8 @@ POST /clients/batch
POST /clients/{id}/power-on
POST /clients/{id}/power-off
POST /clients/{id}/rebootGET /images
POST /images
GET /images/{id}
@@ -1455,8 +1244,8 @@ DELETE /images/{id}
POST /images/{id}/deploy
POST /images/{id}/create
POST /images/{id}/backupGET /commands
POST /commands
@@ -1464,15 +1253,15 @@ GET /command-tasks
POST /command-tasks
PUT /command-tasks/{id}
DELETE /command-tasks/{id}GET /traces
GET /traces/{id}
PUT /traces/{id}
PATCH /traces/{id}/complete
PATCH /traces/{id}/cancelogCore utiliza JSON Web Tokens (JWT) para autenticación:
-POST /auth/login
Content-Type: application/json
@@ -1549,14 +1338,14 @@ class="sourceCode json"> "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "def50200a54b7b..."
}Incluir el token en el header Authorization:
GET /clients
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...POST /auth/refresh
Content-Type: application/json
@@ -1564,10 +1353,10 @@ class="sourceCode bash">{
"refresh_token": "def50200a54b7b..."
}/auth/login/auth/refresh/og-repository/webhook/menu-browserIS_AUTHENTICATED_FULLYLos roles se gestionan en la entidad User:
$user->setRoles(['ROLE_USER']);
$user->setRoles(['ROLE_ADMIN']);Configurado en nelmio_cors.yaml para permitir acceso
desde frontend.
Para producción, habilitar SSL:
SSL_ENABLED=trueConfigurar certificados en /certs/.
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
-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
-Propósito: Cambiar configuración de red de clientes.
Funcionalidad: - Actualiza subnet, IP, configuración de red - Sincroniza con servicios externos (DHCP)
-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
-Propósito: Verificar estado de servicios externos.
Funcionalidad: - Health checks de servicios - Manejo de errores de conexión - Logging de estado
-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
-Propósito: Servicio especializado para creación de trazas.
Funcionalidad: - Validación de parámetros de entrada - Creación de trazas individuales o masivas
-Propósito: Obtener código de partición según tipo y filesystem.
-Propósito: Simplificar nombres de archivos OgLive para mostrar al usuario.
-Propósito: Convertir notación CIDR a IP y máscara de red.
ogCore incluye 18 comandos de consola para tareas administrativas:
-php bin/console app:load-default-user-groupsCrea los grupos de usuarios predeterminados del sistema.
-php bin/console app:load-default-commandsCarga los comandos básicos del sistema.
-php bin/console app:load-default-user-adminCrea el usuario administrador por defecto.
-php bin/console app:load-default-menuCarga menús de arranque predeterminados.
-php bin/console app:load-hardware-typesInicializa la tabla de tipos de hardware.
-php bin/console app:load-organizational-unit-defaultCrea la unidad organizativa raíz.
-php bin/console app:check-client-availabilityEjecución: Cada 1 minuto (cron)
Verifica el estado de conectividad de los clientes y actualiza su estado si no responden en un tiempo determinado.
-php bin/console app:execute-pending-tracesEjecución: Cada 1 minuto (cron)
Procesa las trazas en estado PENDING y las ejecuta en
los clientes correspondientes.
php bin/console app:run-scheduled-command-tasksEjecución: Cada 1 minuto (cron)
Ejecuta tareas programadas que han llegado a su hora de ejecución.
-Comandos para migrar datos desde OpenGnsys 1.1:
-php bin/console opengnsys:migration:organizational-unitphp bin/console opengnsys:migration:hardware-profilephp bin/console opengnsys:migration:clientsphp bin/console opengnsys:migration:osphp bin/console opengnsys:migration:imagephp bin/console opengnsys:migration:software-profilephp bin/console opengnsys:migration:partition-clientphp bin/console app:create-image-repositoriesCrea repositorios de imágenes para desarrollo/testing.
-php bin/console app:charge-example-traceCarga trazas de ejemplo para testing.
-Agregar al crontab:
* * * * * docker exec ogcore-php php bin/console app:execute-pending-traces
* * * * * docker exec ogcore-php php bin/console app:run-scheduled-command-tasksogCore utiliza Doctrine Migrations para gestionar cambios en el esquema de base de datos.
-docker exec ogcore-php php bin/console make:migrationdocker exec ogcore-php php bin/console doctrine:migrations:migratedocker exec ogcore-php php bin/console doctrine:migrations:statusdocker exec ogcore-php php bin/console doctrine:migrations:migrate prevPara migrar datos desde una instalación de OpenGnsys 1.1:
-docker exec ogcore-php php bin/console doctrine:database:create --connection=og_1docker exec -i ogcore-database mysql -u user -p ogcore_old_og < dump_og_1.1.sqlEjecutar los comandos de migración en orden:
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-profiledocker exec ogcore-database mysqldump -u user -p ogcore > backup_$(date +%Y%m%d).sqldocker exec -i ogcore-database mysql -u user -p ogcore < backup_20251008.sqlogCore utiliza PHPUnit con integración de Symfony y Doctrine.
-docker compose exec php bin/phpunitdocker compose exec php bin/phpunit tests/Functional/ClientTest.phpdocker compose exec php bin/phpunit --coverage-html coverage/Ubicación: tests/Functional/
20 archivos de tests funcionales que prueban: - Endpoints de API -
@@ -1926,8 +1715,8 @@ class="sourceCode php">
$this->assertResponseStatusCodeSame(201);
}
-
Se utilizan Zenstruck Foundry factories (24 factories) para crear datos de prueba:
@@ -1936,32 +1725,32 @@ class="sourceCode php"> 'name' => 'Test PC',
'status' => 'active'
]);
-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
docker compose up -ddocker compose -f docker-compose-deploy.yml up -dEl proyecto incluye Jenkinsfile para CI/CD.
-El proyecto puede empaquetarse como .deb:
./package.shEstructura del paquete en debian/: - Control files -
Postinst/preinst scripts - Systemd service file - Configuración
Crear .env.local con configuración de producción:
# Limpiar caché
docker exec ogcore-php php bin/console cache:clear --env=prod
@@ -1999,19 +1788,19 @@ class="sourceCode bash">
# Optimizar autoloader
docker exec ogcore-php composer dump-autoload --optimize --classmap-authoritativeLogs ubicados en var/log/: - dev.log /
prod.log: Logs de aplicación -
nginx/access.log: Accesos a nginx -
nginx/error.log: Errores de nginx
Los logs también se envían a syslog para centralización.
-Para escalar horizontalmente:
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-interactiondocker exec ogcore-php php bin/console cache:clear
docker exec ogcore-php php bin/console cache:warmupdocker exec ogcore-php composer updatedocker exec ogcore-php php bin/console lexik:jwt:generate-keypair --overwriteScript ejemplo para backup automático:
# Limpiar backups antiguos (>30 días)
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -deleteGET /health# PHP
@@ -2085,8 +1874,8 @@ class="sourceCode bash">
# MariaDB
docker exec ogcore-database mysqladmin -u user -p statusConfigurar logrotate:
/var/www/html/ogcore/var/log/*.log {
@@ -2099,51 +1888,51 @@ class="sourceCode bash"> sharedscripts
}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
Propósito: Gestión de DHCP dinámico.
Funcionalidades: - Agregar clientes a DHCP - Eliminar clientes de DHCP - Actualizar configuración - Gestión de subredes
-Propósito: Gestión de archivos de arranque PXE.
Funcionalidades: - Crear archivos de arranque - Actualizar plantillas PXE - Eliminar configuraciones - Sincronización de menús
-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
-Propósito: Integración con sistema de escritorios remotos.
Funcionalidades: - Autenticación - Obtener service pools - Calcular disponibilidad - Gestión de reservas
-Propósito: Versionado de imágenes con Git.
Funcionalidades: - Backup a repositorio Git - Versionado automático - Recuperación de versiones - Sincronización
-Propósito: Notificaciones push en tiempo real.
Eventos publicados: - Cambio de estado de clientes -
@@ -2157,14 +1946,14 @@ class="sourceCode javascript"> console.log('Client updated:', data);
};
Ver CHANGELOG.md para el historial completo de
cambios.
Versiones destacadas:
@@ -2260,10 +2049,10 @@ aulasPara contribuir al proyecto:
git push origin feature/nueva-funcionalidad
Usar el sistema de Issues del repositorio:
Template de Bug:
**Descripción del bug**
@@ -2319,10 +2108,10 @@ Si aplica, añadir screenshots.
- Versión: [ej. 0.5.0]
- Browser: [ej. Firefox 118]swagger-assets/img_bbdd.pngProyecto desarrollado por el equipo de OpenGnsys en colaboración con universidades participantes.
-Proyecto propietario. Ver archivo LICENSE para más
información.
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
+|-- 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
Ver archivo .env para todas las variables de entorno
disponibles.