Octubre 2025
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.
El propósito principal de ogCore es:
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)
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.
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 |
+--------------+--------------+--------------+----------------+| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
git clone <url-del-repositorio> ogcore
cd ogcoreAsegúrate de que los puertos 8080 y 3306 no estén en uso:
sudo lsof -i :8080
sudo lsof -i :3306docker compose up --build -ddocker psDeberías ver tres contenedores activos: - ogcore-nginx -
ogcore-php - ogcore-database
docker exec ogcore-php composer installdocker exec ogcore-php php bin/console lexik:jwt:generate-keypair --overwrite# 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-commandsAbre tu navegador y accede a:
http://127.0.0.1:8080/docsDeberías ver la documentación Swagger de la API de ogCore.
El archivo .env contiene las variables de configuración
principales:
# 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=falseEdita config/packages/nelmio_cors.yaml para configurar
CORS según tus necesidades.
La configuración de API Platform se encuentra en
config/packages/api_platform.yaml.
Para entornos de producción, utiliza el archivo
docker-compose-deploy.yml:
docker compose -f docker-compose-deploy.yml up -dAsegú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
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/docs{
"@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"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "PC-01",
"mac": "00:11:22:33:44:55",
"ip": "192.168.1.100",
"status": "active"
}Todas las colecciones soportan paginación:
GET /clients?page=1&itemsPerPage=30Respuesta:
{
"@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"
}
}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}
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}/rebootGET /images
POST /images
GET /images/{id}
PUT /images/{id}
DELETE /images/{id}
POST /images/{id}/deploy
POST /images/{id}/create
POST /images/{id}/backupGET /commands
POST /commands
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}/cancel| 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 |
ogCore utiliza JSON Web Tokens (JWT) para autenticación:
POST /auth/login
Content-Type: application/json
{
"username": "admin",
"password": "password"
}Respuesta:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "def50200a54b7b..."
}Incluir el token en el header Authorization:
GET /clients
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...POST /auth/refresh
Content-Type: application/json
{
"refresh_token": "def50200a54b7b..."
}/auth/login/auth/refresh/docs/opengnsys/rest/* (webhooks)/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: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-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: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-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 - Flujos completos - Integraciones
Ejemplo:
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);
}Se utilizan Zenstruck Foundry factories (24 factories) para crear datos de prueba:
ClientFactory::createOne([
'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:
APP_ENV=prod
APP_DEBUG=0
DATABASE_URL="mysql://user:pass@localhost:3306/ogcore"
# ... más configuración# 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-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:
#!/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 -deleteGET /health# PHP
docker exec ogcore-php php -v
# Nginx
docker exec ogcore-nginx nginx -t
# MariaDB
docker exec ogcore-database mysqladmin -u user -p statusConfigurar logrotate:
/var/www/html/ogcore/var/log/*.log {
daily
rotate 14
compress
delaycompress
notifempty
create 0640 www-data www-data
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 - Actualización de trazas - Cambios en comandos - Alertas y notificaciones
Suscripción del cliente:
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);
};Ver CHANGELOG.md para el historial completo de
cambios.
Versiones destacadas:
Para contribuir al proyecto:
git checkout -b feature/nueva-funcionalidadgit commit -am 'Añade nueva funcionalidad'git push origin feature/nueva-funcionalidadUsar 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]swagger-assets/ogCore.postman_collection.zipswagger-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.
| 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 |
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
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