Ambientes y despliegue

Objetivo

Documentar qué ambientes existen, cómo se despliega sy-energy y qué pasa durante un despliegue.

Audiencia

Desarrollo interno y DevOps.

Estado documental

• Estado: Borrador
• Última actualización: 2026-08-02
• Owner: Pendiente
• SME requerido: DevOps / líder técnico
• Fuente resumida: configuración de Deployer del repositorio.

Ambientes

El repositorio declara una configuración de despliegue por destino:

Ambiente	Propósito
Local	Desarrollo. Hay configuración de Docker para levantarlo.
Development	Validación previa.
Testing	Pruebas.
Producción — participante A	Operación real de un participante.
Producción — participante B	Operación real de otro participante.

Cada participante productivo tiene su propio archivo de despliegue, su propio host y su propio directorio en el servidor. No comparten base de datos ni colas.

Un despliegue no alcanza a todos

Desplegar a un participante no actualiza al otro. Al liberar un cambio que afecta a ambos, hay que ejecutar el despliegue una vez por participante y verificar los dos.

Herramienta

El despliegue usa Deployer con la receta de Laravel, desde la rama principal del repositorio. Se conservan las últimas 5 versiones desplegadas, lo que permite volver atrás.

PHP-FPM del servidor: 8.5.

Qué hace un despliegue

La secuencia declarada, en orden:

Paso	Qué ocurre
Preparación	Se crea el directorio de la nueva versión.
Secretos	Se colocan las variables de ambiente en el servidor.
Dependencias	Instalación de dependencias de PHP.
Permisos y enlaces	Propietario de archivos y enlace de storage.
Limpieza de caché	Se limpian cachés de configuración y rutas.
Migraciones	Se ejecutan las migraciones de base de datos.
Assets	Instalación de dependencias de node y compilación de frontend para producción.
Reinicio de colas	Se señala a los workers que terminen y reinicien con el código nuevo.
Publicación	Se cambia el enlace simbólico a la nueva versión.
Limpieza	Se eliminan las versiones más antiguas.

Dos pasos merecen atención:

Migraciones. Corren automáticamente en cada despliegue. Una migración pesada sobre una tabla grande puede bloquear la operación mientras corre.

Reinicio de colas. Los workers terminan el trabajo en curso y se reinician. Si un despliegue ocurre a media cadena diaria, un trabajo largo puede quedar interrumpido.

Ventanas de despliegue

Evitar desplegar:

Cuándo	Por qué
05:00 – 08:30	Corre la cadena diaria completa de ECD y facturación.
Día 1 y día 4 del mes	Ciclo mensual de facturación. Se emiten documentos fiscales.
Lunes por la mañana	Corre el bot de referencia bancaria.

Validación posterior al despliegue

1. La aplicación responde y permite iniciar sesión.
2. Los workers de Supervisor están en estado RUNNING.
3. php artisan queue:failed no creció respecto a antes del despliegue.
4. El cron sigue activo.
5. La primera tarea programada posterior al despliegue corrió correctamente.

Rollback

Deployer conserva las últimas 5 versiones, así que revertir el código es posible.

Las migraciones no se revierten solas

Volver a una versión anterior del código no deshace las migraciones ya aplicadas. Si el despliegue incluyó un cambio de esquema, el rollback puede dejar el sistema en un estado inconsistente.

Antes de revertir: confirmar si hubo migraciones y coordinar con desarrollo.

Configuración de ambiente

Las variables se colocan en el servidor durante el despliegue; no viven en el repositorio. El detalle de qué variables existen está en Variables por ambiente.

Riesgos y gaps

• No está documentado quién autoriza un despliegue a producción ni cuál es la ventana acordada.
• No existe procedimiento documentado de rollback de base de datos.
• Las migraciones automáticas en cada despliegue no tienen una verificación previa documentada de su impacto.
• No está documentado cómo se mantienen sincronizadas las configuraciones entre las instancias de participante.
• Falta documentar el pipeline de integración continua, si existe, y qué valida.

Próxima revisión

Tras la validación de DevOps.