# cPanel Hosting & Deployment

## Overview
- Hosting plan: cPanel shared hosting (approx. $70/year ~ KES equivalent). Suitable for small SME production with modest traffic.
- Notes: cPanel is cost-effective but limited for long-running processes (no Supervisor). Use cron-based workarounds or managed VPS for heavy queue usage.

## Pre-deployment checklist
- cPanel account credentials and FTP/SFTP/SSH access (SSH recommended). 
- PHP version >= 8.0 and required PHP extensions installed (PDO, BCMath, OpenSSL, Mbstring, JSON, cURL, Zip).
- MySQL/MariaDB database created; DB user and password ready.
- Domain DNS pointed to hosting and SSL enabled (AutoSSL or Let's Encrypt).
- Git or FTP workflow decided (Git push via cPanel Git or SFTP upload).

## Initial deployment steps
1. Upload code (via Git or SFTP) to `public_html/` or preferred document root.
2. Place `.env` in project root and set DB, MPESA, mail and other credentials.
3. SSH into the server (if available) and run:

```bash
composer install --no-dev --optimize-autoloader
php artisan key:generate
php artisan migrate --force
php artisan storage:link
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

4. Set correct permissions (Laravel typical):

```bash
chown -R <cpanel-user>:<cpanel-user> storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

5. Ensure document root points to `public/` (use cPanel settings to adjust if code is outside `public_html`).

## Updating the application (deploy updates)
- Pull or upload updated code to the server.
- From SSH or cPanel Terminal, run:

```bash
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan storage:link
```

- If SSH is not available, upload a release zip, extract, and perform the same steps via cPanel Terminal or provide a maintenance window to run commands locally then re-upload.

## Queues and scheduled tasks
- cPanel usually does not provide Supervisor. Use cron as a workaround:
  - Create a cron entry to run every minute that processes jobs and stops when empty:

```bash
* * * * * cd /home/<cpanel-user>/path-to-project && php artisan queue:work --stop-when-empty --sleep=3 --tries=3 >> /home/<cpanel-user>/storage/logs/cron-queue.log 2>&1
```

- Register Laravel scheduler in cPanel cron:

```bash
* * * * * cd /home/<cpanel-user>/path-to-project && php artisan schedule:run >> /dev/null 2>&1
```

## Backups
- Configure daily DB dump via cPanel Backup or cron using `mysqldump` and copy to remote storage (S3, Dropbox, or alternate server).

Example DB dump cron (daily at 02:00):

```bash
0 2 * * * mysqldump -u DB_USER -p'PASSWORD' DB_NAME > /home/<cpanel-user>/backups/db-$(date +\%F).sql
```

- Keep at least 14 days of DB backups and weekly full file backups.

## SSL
- Enable cPanel AutoSSL or install Let's Encrypt if available. Ensure HTTPS redirect in `.htaccess` or Nginx config.

## Rollback strategy
- Always tag releases and keep a recent DB snapshot before running migrations.
- To rollback code: redeploy previous tag.
- To rollback DB (if supported): use `php artisan migrate:rollback` for last batch, or restore from DB dump for full restore.

## Security best practices
- Protect `.env` and storage; set correct permissions.
- Use strong, unique DB passwords and change default cPanel account password.
- Enable ModSecurity and cPanel-provided security features.
- Keep PHP and Composer dependencies updated; run security updates monthly.

## Monitoring & alerts
- Configure uptime monitoring (UptimeRobot) and basic health checks.
- Monitor logs in `storage/logs/` and set simple log rotation.

## Limitations & recommendations
- cPanel is ideal for small SMEs with light traffic. If you expect heavy queue loads, high TPS, or strict SLAs, upgrade to a VPS or managed cloud (DigitalOcean, AWS) where Supervisor and dedicated resources are available.
- For reliable queue handling, consider moving queue workers to a small VPS and keeping the app on cPanel if desired.

## Maintenance & cost
- Hosting: ~$70/year (billed annually).
- Recommend monthly maintenance retainer (optional): KES 10,000–40,000 depending on SLA.
- One-time deployment/setup fee (if we handle it): KES 25,000–75,000.

## Handover checklist (what we will deliver)
- Access credentials and connection instructions.
- `README` with deployment and rollback steps.
- Cron entries for scheduler and queue.
- Backup schedule and retention policy.
- List of environment variables and secrets to set in cPanel.

---

If you want, I can also:
- Draft a one-page `SOW` entry describing the cPanel hosting option and fees, or
- Add these cron entries and the `README` to the repository under `docs/` and `deploy/`.
