CI4 Apex Deploy System

Documentación

Introducción

CI4 Apex Deploy System

CI4 Apex Deploy System es el sistema base profesional para desarrollar y desplegar aplicaciones CodeIgniter 4 completamente contenerizadas, con motor de base de datos intercambiable y listas para producción. Descomprime, configura y ejecuta en menos de 10 minutos.

El kit resuelve de raíz los problemas más comunes al arrancar un proyecto serio:

  • Infraestructura Docker lista desde el primer arranque
  • Entorno CI4 funcional desde el primer boot
  • Motor de base de datos intercambiable — MySQL o PostgreSQL, a un comando de distancia
  • Panel de operaciones VIAVI en /viavi/ para health, colas, perfil y controles del kit
  • VIAVI Intelligence en el panel (Professional/Ultimate) — diagnóstico de entorno, resumen de logs y generación de código, con Claude (Anthropic) usando tu propia API key
  • Base sólida para pipelines CI/CD reales
  • Production-ready desde el día uno
Componente Versión Rol
CodeIgniter 4 ^4.7 Framework MVC, Shield auth, Queue
PHP 8.5 (FPM) Runtime, FastCGI
Nginx 1.28-alpine Reverse proxy, archivos estáticos
Base de datos MySQL 9.7 o PostgreSQL 16 Intercambiable vía make db-switch-*
Redis 8.8-alpine Cache, sesiones, backend de colas
Supervisor system Gestiona php-fpm en el contenedor de producción
Sentry SDK ^4.10 Captura de errores en producción
PHPStan ^2.2 Análisis estático nivel 6, cero errores
Rector ^2.5 Refactorización automatizada para PHP 8.5
PHPUnit ^11.2 Tests unitarios, bootstrap, sesión y BD
pcov PECL Driver de cobertura (solo desarrollo)

Requisitos previos

PHP y Composer no son necesarios en tu máquina local — todo corre dentro de contenedores.

  • Docker Desktop 4.x o Docker Engine 24.x con Compose v2
  • GNU Make
  • Git 2.x

Guía de implementación

1. Descomprime el kit

Descomprime el archivo .zip descargado en tu carpeta de proyecto vacía.

2. Inicia el entorno

$ make setup
# Ejecuta: build + up + migrate + seed + healthcheck

No necesitas crear el .env manualmente — make setup lo genera automáticamente a partir de .env.example si no existe.

¿Vas a arrancar directo con PostgreSQL en vez de MySQL? En ese caso sí necesitas el .env creado antes de cambiar de motor (los comandos de switch lo editan in place): cp .env.example .env && make db-switch-postgres && make setup.

3. Verifica el estado

$ curl http://localhost:8080/health
// Respuesta esperada
{
  "status": "ok",
  "database": { "status": "ok" },
  "redis": { "status": "ok" }
}

4. Quality gates

$ make stan # PHPStan nivel 6 — sin errores
$ make rector # Rector dry-run — sin cambios
$ make test # PHPUnit — todos los suites deben pasar

Configuración

Motor de base de datos

Cambia entre MySQL y PostgreSQL en cualquier momento. Cada comando detiene el stack activo, reescribe .env y apunta Docker Compose al archivo correspondiente:

$ make db-switch-mysql
$ make db-switch-postgres

Ningún otro comando cambia — make up, make migrate, make test, etc. funcionan igual sin importar el motor activo.

KIT_STAGE

Controla qué se sirve en /. Puedes cambiarlo desde el panel de operaciones o con Make:

Valor Comportamiento
setup Pantalla de onboarding VIAVI (default)
building Pantalla de onboarding mientras construyes
launched Sirve tu aplicación en /
$ make launch # KIT_STAGE=launched
$ make stage-building # KIT_STAGE=building
$ make stage-setup # KIT_STAGE=setup

En Railway/Render el archivo .env es efímero — configura KIT_STAGE en su panel de variables. En VPS el archivo persiste en disco y el switch desde el panel funciona correctamente.

Credenciales por defecto

Cambia estas credenciales inmediatamente después del primer login.
Email admin@local.test
Password Password123!

Recuperación de cuenta

Si pierdes la contraseña de admin, tienes dos opciones:

Opción 1 — Flujo web con recovery key

Requiere que RECOVERY_KEY ya esté definida en tu .env (o en las variables de Railway) antes de perder el acceso — configúrala ahora, no cuando ya la necesites.

1. Genera la clave. El comando usa OpenSSL para crear 32 bytes aleatorios en formato hexadecimal:

$ openssl rand -hex 32

En Windows, PowerShell no trae openssl integrado. Corre el comando desde Git Bash (se instala junto con Git para Windows, que ya tienes) o desde el shell del contenedor: docker compose exec php openssl rand -hex 32 — ambas rutas dan el mismo resultado.

2. Guarda la clave generada. Copia el valor que te devuelve el comando (una cadena de 64 caracteres) y agrégala a tu .env:

RECOVERY_KEY=tu_clave_generada_aquí

En Railway, agrégala como variable de entorno del servicio en vez de en .env (recuerda: .env es efímero ahí). Guárdala también en un gestor de contraseñas — es tu única llave de recuperación si pierdes el acceso al panel.

3. Cuando necesites recuperar el acceso: visita /viavi/profile/reset, confirma el email actual de la cuenta, e ingresa la recovery key que guardaste en el paso 2.

Opción 2 — CLI de emergencia

Requiere acceso al servidor o contenedor (SSH, o la terminal del panel de tu hosting). Regresa la cuenta a las credenciales de fábrica sin importar si configuraste RECOVERY_KEY o no — es el respaldo si nunca la generaste:

$ make reset-admin

Uso

Panel de operaciones VIAVI

El kit incluye un panel de operaciones en /viavi/, siempre disponible independientemente del estado de tu aplicación.

URL Descripción
/viavi/ Panel principal — health, colas, controles
/viavi-dashboard Acceso directo al panel
/viavi/ai VIAVI Intelligence — Professional: solo diagnóstico. Ultimate: completo
/viavi/profile Cambiar email y contraseña
/viavi/commands Referencia de comandos Make
/health Healthcheck público en JSON

VIAVI Intelligence

Disponible en el panel para los tiers Professional y Ultimate. Impulsado por Claude (Anthropic), usando tu propia API key — el kit nunca intermedia ni cobra por esas llamadas.

Capacidad Professional Ultimate
Diagnóstico de entorno
Resumen de logs —
Generación de código —

El contenido de logs se escanea y redacta antes de enviarse a la API para evitar exponer contraseñas, tokens o API keys. El código generado siempre se devuelve como texto para revisión manual — nunca se escribe a disco automáticamente.

Arrancar tu aplicación

  1. Edita app/Views/home.php con tu pantalla principal.
  2. Define tus rutas en app/Config/Routes.php.
  3. Edita app/Controllers/Home.php con tu lógica.
  4. Activa tu app:
$ make launch

Rutas reservadas por el kit — no las sobreescribas: /viavi/*, /viavi-dashboard, /health, /login, /post-login, /set-organization/*

Comandos disponibles

$ make setup # Build, up, migrate, seed, healthcheck
$ make test # PHPUnit — todos los suites
$ make stan # PHPStan nivel 6
$ make rector # Rector dry-run
$ make migrate # Migraciones pendientes
$ make seed # Ejecutar seeders
$ make db-switch-mysql # Cambiar motor a MySQL
$ make db-switch-postgres # Cambiar motor a PostgreSQL
$ make launch # KIT_STAGE=launched
$ make down-v # docker compose down -v
$ make uninstall # Destruye volúmenes, resetea .env (pide confirmación)
$ make deploy # Deploy (ver scripts/deploy.sh)

Despliegue

El kit incluye guías de despliegue para tres plataformas. Selecciona la que mejor se adapte a tu proyecto.

Railway

Ultimate Tier requerido

Imagen de un solo contenedor. Las variables de entorno se inyectan directamente — el archivo .env no se usa en producción.

$ railway login
$ railway link
$ railway run php spark migrate --all

KIT_STAGE debe configurarse en el panel de variables de Railway, no en .env.

Render

Ultimate Tier requerido

Render no ofrece MySQL nativo — usa Railway MySQL como proveedor externo (recomendado: soporte nativo de llaves foráneas y copia/pega simple de credenciales) o Aiven/PlanetScale como alternativas.

VPS (Ubuntu 24.04)

Ultimate Tier requerido

Control total. El archivo .env persiste en disco, por lo que el switch de KIT_STAGE desde el panel VIAVI funciona correctamente en producción.

$ ./scripts/deploy.sh v1.0.0
# backup → pull → migrate → healthcheck

FAQ

Conocimiento básico es suficiente. El kit incluye documentación clara y scripts que hacen el trabajo pesado. Con make setup tienes el entorno corriendo en minutos.

Sí. Cualquier sistema con Docker Desktop instalado puede correr este kit sin modificaciones.

Sí. El motor es intercambiable con un comando (make db-switch-mysql / make db-switch-postgres), sin cambiar tu código — las migraciones incluidas son portables entre ambos motores.

El kit corre PHP 8.5 (FPM) fijo dentro del contenedor Docker — esa versión no es intercambiable como el motor de base de datos. Tu máquina local no necesita tener PHP instalado, pero tu código debe ser compatible con PHP 8.5 para funcionar dentro del kit.

Sí, con excepciones. Las rutas reservadas del kit (/viavi/*, /health, /login) no deben sobreescribirse. Todo lo demás es tuyo.

No. El panel requiere autenticación. Solo usuarios con credenciales válidas pueden acceder a /viavi/.

Sí. La licencia permite uso en proyectos propios y de clientes. Una licencia por proyecto.