CI4 Apex Deploy System
DocumentationIntroduction
CI4 Apex Deploy System
CI4 Apex Deploy System is the professional base system for developing and deploying fully containerized, production-ready CodeIgniter 4 applications with a switchable database engine. Unzip, configure, and run in under 10 minutes.
The kit solves the most common problems when starting a serious project:
- Docker infrastructure ready out of the box
- Functional CI4 environment from the first boot
- Switchable database engine — MySQL or PostgreSQL, one command apart
- VIAVI Operations Panel at
/viavi/for health, queues, profile and kit controls - VIAVI Intelligence in the panel (Professional/Ultimate) — environment diagnostics, log summaries and code scaffolding, powered by Claude (Anthropic) using your own API key
- Foundation for real CI/CD pipelines
- Production-ready from day one
| Component | Version | Role |
|---|---|---|
| CodeIgniter 4 | ^4.7 | MVC framework, Shield auth, Queue |
| PHP | 8.5 (FPM) | Runtime, FastCGI |
| Nginx | 1.28-alpine | Reverse proxy, static files |
| Database | MySQL 9.7 or PostgreSQL 16 | Switchable via make db-switch-* |
| Redis | 8.8-alpine | Cache, sessions, queue backend |
| Supervisor | system | Manages php-fpm in prod container |
| Sentry SDK | ^4.10 | Error capture in production |
| PHPStan | ^2.2 | Static analysis level 6, zero errors |
| Rector | ^2.5 | Automated refactoring for PHP 8.5 |
| PHPUnit | ^11.2 | Unit, bootstrap, session, and DB testing |
| pcov | PECL | Coverage driver (dev only) |
Prerequisites
PHP and Composer are not required on the host machine — everything runs inside containers.
- Docker Desktop 4.x or Docker Engine 24.x with Compose v2
- GNU Make
- Git 2.x
Implementation guide
1. Unzip the kit
Unzip the downloaded .zip file into your empty project folder.
2. Start the environment
You don't need to create .env manually — make setup generates it automatically from .env.example if it doesn't exist.
Starting fresh with PostgreSQL instead of MySQL? In that case you do need .env created before switching (the switch commands edit it in place): cp .env.example .env && make db-switch-postgres && make setup.
3. Verify the status
4. Quality gates
Configuration
Database engine
Switch between MySQL and PostgreSQL at any time. Each command tears down the running stack, rewrites .env, and points Docker Compose at the matching file:
No other command changes — make up, make migrate, make test, etc. all work identically regardless of which engine is active.
KIT_STAGE
Controls what is served at /. Toggle from the operations panel or via Make:
| Valor | Behavior |
|---|---|
setup |
VIAVI onboarding screen (default) |
building |
VIAVI onboarding screen while you build |
launched |
Serves your application at / |
On Railway/Render, .env is ephemeral — set KIT_STAGE in their environment variable panel instead. On VPS the file persists on disk, and the panel switch works correctly.
Default credentials
admin@local.test |
|
| Password | Password123! |
Account recovery
If you lose the admin password, two options are available:
Option 1 — Web flow with recovery key
Requires RECOVERY_KEY to already be set in your .env (or Railway's variables) before you lose access — set it up now, not when you already need it.
1. Generate the key. The command uses OpenSSL to create 32 random bytes in hex format:
On Windows, PowerShell doesn't ship with openssl built in. Run the command from Git Bash (installed alongside Git for Windows, which you already have) or from inside the container's shell: docker compose exec php openssl rand -hex 32 — either path gives the same result.
2. Save the generated key. Copy the value the command returns (a 64-character string) and add it to your .env:
On Railway, add it as a service environment variable instead of in .env (remember: .env is ephemeral there). Also save it in a password manager — it's your only recovery key if you lose access to the panel.
3. When you need to recover access: visit /viavi/profile/reset, confirm the account's current email, and enter the recovery key you saved in step 2.
Option 2 — Emergency CLI
Requires server or container access (SSH, or your host's terminal panel). Forces the account back to factory credentials regardless of whether you set up RECOVERY_KEY — this is the fallback if you never generated one:
Usage
VIAVI Operations Panel
The kit ships with a built-in operations panel at /viavi/, always available regardless of your application's state.
| URL | Description |
|---|---|
/viavi/ |
Main panel — health, queues, kit controls |
/viavi-dashboard |
Shortcut to the operations panel |
/viavi/ai |
VIAVI Intelligence — Professional: diagnose only. Ultimate: full |
/viavi/profile |
Update email and password |
/viavi/commands |
Makefile command reference |
/health |
Public JSON healthcheck for orchestrators |
VIAVI Intelligence
Available in the panel for Professional and Ultimate tiers. Powered by Claude (Anthropic), using your own API key — the kit never proxies or bills for these calls.
| Capability | Professional | Ultimate |
|---|---|---|
| Diagnose environment | ||
| Summarize logs | — | |
| Generate code | — |
Log content is scanned and redacted for anything resembling a password, token, or API key before it is ever sent to the API. Generated code is always returned as text for manual review — never written to disk automatically.
Starting your application
- Edit app/Views/home.php with your application home screen.
- Define your routes in app/Config/Routes.php.
- Edit app/Controllers/Home.php with your root controller logic.
- Launch your app:
Routes reserved by the kit — do not overwrite: /viavi/*, /viavi-dashboard, /health, /login, /post-login, /set-organization/*
Available commands
Deployment
The kit includes deployment guides for three platforms. Select the one that best fits your project.
Railway
Ultimate Tier required
Single-container image. Environment variables are injected directly — the .env file is not used in production.
KIT_STAGE must be set in Railway's Variables panel, not in .env.
Render
Ultimate Tier required
Render does not offer MySQL natively — use Railway MySQL as an external provider (recommended: native foreign key support and simple credential copy-paste) or Aiven/PlanetScale as alternatives.
VPS (Ubuntu 24.04)
Ultimate Tier required
Full control. The .env file persists on disk, so the KIT_STAGE switch from the VIAVI panel works correctly in production.