# cPanel / Passenger Deployment (Python 3.9+)

## Recommended layout

Keep the application outside `public_html`:

```text
/home/CPANEL_USER/al_wattan_ovr/
  passenger_wsgi.py
  ovrapp/
  storage/
  instance/
  .env
```

The subdomain's document root can remain a small public folder managed by cPanel's Python Application setup; Passenger loads `passenger_wsgi.py` from the application root.

## Steps

1. In cPanel **Setup Python App**, create an application with Python 3.9 or newer.
2. Set Application Root to `al_wattan_ovr` and Startup File to `passenger_wsgi.py`.
3. Upload and extract the package into `/home/CPANEL_USER/al_wattan_ovr`.
4. Activate the cPanel virtual environment and install dependencies:

   ```bash
   source /home/CPANEL_USER/virtualenv/al_wattan_ovr/3.9/bin/activate
   cd /home/CPANEL_USER/al_wattan_ovr
   pip install -r requirements.txt
   ```

5. Create a MariaDB database/user in cPanel and grant all privileges for that database.
6. Copy `.env.example` to `.env`. Set a strong `SECRET_KEY`, database URL, real HTTPS base URL, `SESSION_COOKIE_SECURE=true`, and optional SMTP settings.
7. Restrict permissions:

   ```bash
   chmod 600 .env
   chmod 700 storage instance
   chmod 700 storage/uploads storage/logs
   ```

8. Initialize once:

   ```bash
   python manage.py init-db --admin-username admin --admin-email YOUR_EMAIL
   ```

9. Restart the Python application from cPanel and open `/healthz`.
10. Sign in, change the temporary password, configure branches/departments/users, and test the workflow.

## Cron reminder

Use the exact virtual-environment path shown by cPanel:

```cron
*/30 * * * * cd /home/CPANEL_USER/al_wattan_ovr && /home/CPANEL_USER/virtualenv/al_wattan_ovr/3.9/bin/flask --app wsgi.py send-due-reminders >> /home/CPANEL_USER/al_wattan_ovr/storage/logs/reminders.log 2>&1
```

## Troubleshooting

- Run `python manage.py check` inside the cPanel virtual environment.
- Review `storage/logs/app.log`, Passenger `stderr.log`, and the cPanel application log.
- A 500 page includes a short error reference; search `storage/logs/app.log` for that reference.
- Confirm the database hostname, user grants, password encoding, and `charset=utf8mb4`.
- Do not make `storage/uploads` public to work around a download issue.