# Deploy to cPanel with GitHub Actions

This follows Sharqiah's `.github/workflows/deploy-cpanel.yml`: manual trigger, production environment, PHP 8.4 / Node 22 build, and SSH/rsync deployment. It runs the focused WhatsApp/campaign tests before removing development dependencies and building assets. The full legacy test suite is not a deployment gate because it currently has known failures.

## GitHub configuration

Create a GitHub environment named **production** under Settings → Environments. Add these environment variables:

| Variable | Value |
| --- | --- |
| `CPANEL_SSH_HOST` | cPanel SSH hostname or IPv4 address |
| `CPANEL_SSH_USER` | cPanel account username |
| `CPANEL_SSH_PORT` | SSH port; default `22` |
| `CPANEL_DEPLOY_PATH` | Absolute path to this Laravel application's root directory |
| `CPANEL_PHP_BINARY` | PHP CLI executable; default `/usr/local/bin/ea-php84` |

Paths must contain only letters, digits, underscores, dots, slashes, and hyphens. The target must be a directory dedicated to this application: rsync deletes files absent from the deployment artifact, except excluded persistent paths. Do not target the account home or a directory shared with other sites.

Add these environment secrets:

| Secret | Value |
| --- | --- |
| `CPANEL_SSH_KEY` | Private SSH key whose public key is authorized in cPanel |
| `CPANEL_SSH_KNOWN_HOSTS` | Verified SSH host-key entry for that host and port |

Obtain a candidate host-key entry from a trusted machine with `ssh-keyscan -p PORT -H HOST`, verify its fingerprint against your hosting provider or another trusted source, then save the entry as `CPANEL_SSH_KNOWN_HOSTS`. Unlike the reference workflow, this workflow pins the verified host key instead of trusting a fresh scan during every deployment.

## Server preparation

1. Enable SSH access for the cPanel account and authorize the deployment public key. Install rsync and a PHP 8.3+ CLI with the application's required extensions. PHP 8.4 is used for the build; use a matching server version where possible.
2. Create the dedicated deployment directory and its production `.env`. Set `APP_KEY` once and retain it: device tokens are encrypted with it. Configure the database, `APP_URL`, `QUEUE_CONNECTION=database`, `CACHE_STORE=database`, and Evolution credentials. The workflow never uploads a local `.env` or generates a production key.
3. Set the domain/subdomain document root to `CPANEL_DEPLOY_PATH/public`. Avoid exposing the Laravel project root. The old `.cpanel.yml` refers to `/home/platformdgtlorg/public_html/campaigns`; that historical location is not assumed or selected automatically by this workflow.
4. Ensure the cPanel user can write `storage` and `bootstrap/cache`. Persistent storage, public storage/upload links, environment files, and SQLite databases are excluded from synchronization.
5. Configure Supervisor for `php artisan queue:work database --queue=broadcasts,campaigns,default --timeout=60 --tries=3`. Run `php artisan schedule:run` every minute through cPanel Cron Jobs. Reverb is installed; configure its credentials, public WSS proxy, and Supervisor program using [the Reverb guide](reverb.md). Deployment restarts existing workers; it does not create Supervisor programs or install Reverb.
6. Use this Actions workflow instead of also invoking cPanel's legacy Git deployment tasks for the same directory.

## Run a deployment

Commit and push the workflow and deployment script. Open **Actions → Deploy to cPanel → Run workflow**, select the branch, and run it. Deployments are serialized; a new run does not cancel one already in progress. No push-triggered deployment is configured, matching Sharqiah.

The workflow verifies SSH access, the server PHP version, rsync, and the production `.env` before upload. It preserves application cache locks, runs migrations, creates configured storage links, rebuilds Laravel caches, and signals queue/Reverb restarts. Supervisor must run under the same application environment/cache configuration for restart signals to take effect.

This is an in-place rsync deployment, matching the reference project. It is not an atomic release switch or an automatic database rollback. Back up the database/uploads before schema-changing releases and inspect failed runs before repeating them. No deployment has been run merely by adding these files.
