# GitHub build and cPanel deployment webhook

Repository: https://github.com/TILEFIN-IT-SOLUTIONS/whatsapp
Application: /home/tilefin/whatsapp
Public document root: /home/tilefin/whatsapp/public
PHP CLI: /usr/local/bin/ea-php84

The main workflow now uses the OnePageCard-style build branch and authenticated HTTP deployment hook. It does not use CPANEL_HOST, CPANEL_USERNAME, CPANEL_PASSWORD, STAGING_PATH, CPANEL_SSH_* or CPANEL_PHP_BIN GitHub settings. The previous SSH helper is retained as a manual alternative only.

## GitHub setup

Add a repository secret DEPLOY_WEBHOOK_TOKEN with a new random 64-character hexadecimal value. Set the same value in the SERVER .env. A local development .env is not uploaded to the server.

Pushes to main run tests, build vendor dependencies, and publish production-deploy using the built-in GitHub Actions token. GitHub then calls POST https://whatsapp.tilefin.com/api/webhooks/deploy. The first call will fail until the initial server installation below is complete; the build branch will still be available. GitHub organization policy must permit Actions contents:write. Do not manually develop on production-deploy; each build replaces it.

## One-time server installation

1. In cPanel SSH Access, create a dedicated key for this server to READ this GitHub repository. Add the public key in GitHub Settings -> Deploy keys, without write access. Configure the server SSH client to use this key for github.com and verify GitHub's host-key fingerprint through GitHub documentation before accepting it. Never share the private key.
2. After Actions has created production-deploy, clone it into a NEW empty directory, e.g. /home/tilefin/whatsapp-install. Do not overwrite an existing .env or folder blindly:

```bash
git clone --branch production-deploy --single-branch git@github.com:TILEFIN-IT-SOLUTIONS/whatsapp.git /home/tilefin/whatsapp-install
```

3. Use File Manager to move the prepared application files, including .git and hidden files, into /home/tilefin/whatsapp after backing up any existing contents. Preserve the production .env if one already exists. A fresh install can copy .env.example to .env before configuring it.
4. Set production database credentials, APP_ENV=production, APP_DEBUG=false, APP_URL=https://whatsapp.tilefin.com, provider/signing configuration, and these values:

```dotenv
DEPLOY_WEBHOOK_ENABLED=true
DEPLOY_WEBHOOK_TOKEN=the_same_value_as_the_Github_secret
DEPLOY_PHP_BIN=/usr/local/bin/ea-php84
DEPLOY_GIT_BIN=/usr/bin/git
```

Confirm command -v git and change DEPLOY_GIT_BIN if needed. Set PHP 8.4 for the website in MultiPHP Manager as well. PHP web must allow proc_open. InMotion request time limits must accommodate Git fetch and migrations.

5. Run in Terminal:

```bash
cd /home/tilefin/whatsapp
touch .tilefin-deploy-target
mkdir -p storage/framework/cache/data storage/framework/sessions storage/framework/views storage/logs bootstrap/cache
/usr/local/bin/ea-php84 artisan config:clear
# ONLY for a fresh installation with an empty APP_KEY:
/usr/local/bin/ea-php84 artisan key:generate
/usr/local/bin/ea-php84 artisan migrate --force
/usr/local/bin/ea-php84 artisan config:cache
/usr/local/bin/ea-php84 artisan route:cache
```

Never regenerate an existing APP_KEY: it protects stored encrypted data. Keep database/storage backups before migrations.

6. Confirm HTTPS serves the API and rerun Deploy cPanel in GitHub Actions. Queue workers and scheduler require separate setup per docs/deployment.md and InMotion's plan limits.

## Safety and recovery

Deployment is disabled by default and rejects missing/short/wrong tokens. It accepts only POST, a 40-character source commit, and the fixed production-deploy branch from the server's configured origin. A local filesystem lock prevents overlapping deployments; no cache flush can remove the lock. The fetched build's .deployed-source must equal the requested source commit before any checkout/migration.

The script resets tracked application files; .env, storage data and databases stay untracked and are preserved. Never commit server secrets or edit tracked code on the server. Deploy only into this dedicated app checkout. Maintenance mode wraps checkout/migrations; failures leave maintenance enabled for manual recovery. The deploy route remains reachable in maintenance mode so an authenticated retry can recover. A broken app bootstrap requires Terminal recovery.

Failures return only a safe step name, not command output that might expose credentials. Inspect logs and rerun the failing artisan command in Terminal. After resolving the issue run artisan up or retry the workflow. Database migrations are not automatically rolled back. A successful hook confirms the source commit, and a separate public HTTPS check confirms reachability; neither proves live WhatsApp delivery.