# Mr Bismarck Super Platform — cPanel Deployment Guide This guide gets the Laravel 12 backend running on a cPanel-managed shared hosting account so you can test it online. --- ## 0. What's in this ZIP ``` mrbismarck/ ├── app/ Application code (controllers, models, services...) ├── bootstrap/ Framework bootstrap (app.php, providers.php) ├── config/ Configuration files ├── database/ │ ├── migrations/ Laravel migrations (source of truth for schema) │ ├── seeders/ Demo data seeders │ ├── factories/ Test factories │ └── sql/ │ └── mrbismarck_schema.sql ⬅ Manual schema import (fallback) ├── public/ Web root — index.php, .htaccess ├── resources/ Views (PDF templates etc.) ├── routes/ api.php, web.php, console.php ├── storage/ Logs, cache, sessions (needs write permission) ├── tests/ Pest test suite ├── .env.example Copy to .env and fill in your values ├── artisan Laravel CLI ├── composer.json ├── deploy.sh ⬅ One-shot setup script (run via SSH) └── DEPLOYMENT_GUIDE.md This file ``` --- ## 1. Requirements Check In cPanel, confirm: - **PHP version**: 8.3 (MultiPHP Manager → set PHP 8.3 for your domain) - **PHP extensions enabled** (MultiPHP INI Editor): `pdo_mysql`, `mbstring`, `bcmath`, `ctype`, `fileinfo`, `json`, `openssl`, `tokenizer`, `xml`, `curl`, `gd` or `imagick`, `redis` (optional — only if you'll run queues/Horizon) - **SSH access** (Security → SSH Access). Most things below assume SSH + Composer access via cPanel's "Setup Node.js/Python/etc" or Terminal app. If you truly have NO SSH/Composer, see **Section 7 (No-SSH fallback)**. - **MySQL database** created via *MySQL® Databases* (note the DB name, username, password — cPanel usually prefixes these with `cpaneluser_`). --- ## 2. Upload the files **Recommended layout — keep the app OUTSIDE `public_html`:** 1. Create a folder alongside `public_html`, e.g. `~/mrbismarck/` (use File Manager → "+ Folder" at the home directory level, not inside public_html). 2. Upload this ZIP there and extract it, so you end up with `~/mrbismarck/app`, `~/mrbismarck/public`, etc. 3. In cPanel → **Domains** (or "Addon Domains" / "Subdomains"), set the **Document Root** for the domain/subdomain you're testing on to: ``` /home/cpanelusername/mrbismarck/public ``` This is the cleanest setup — Laravel's `public/` folder becomes your web root directly, and everything else (`.env`, `app/`, etc.) stays outside web-accessible space. **If your host does NOT let you change the Document Root** (some budget shared plans only allow `public_html`): 1. Upload & extract the ZIP into `~/mrbismarck/` (outside `public_html`) as above. 2. Then copy (not move) the **contents** of `~/mrbismarck/public/` into `public_html/` (i.e. `public_html/index.php`, `public_html/.htaccess`, `public_html/build/` etc. — directly inside `public_html`, not in a subfolder). 3. Edit the copied `public_html/index.php` and change the two `require` paths from `__DIR__.'/../vendor/autoload.php'` and `__DIR__.'/../bootstrap/app.php'` to point at your app folder, e.g.: ```php require __DIR__.'/../mrbismarck/vendor/autoload.php'; $app = require_once __DIR__.'/../mrbismarck/bootstrap/app.php'; ``` 4. Delete the root `.htaccess` included in this ZIP (it's only for the "whole project in public_html" approach, which is **NOT recommended** for security — it would expose `.env` and `app/` source if misconfigured). --- ## 3. Configure `.env` ```bash cd ~/mrbismarck cp .env.example .env nano .env # or edit via File Manager ``` Set at minimum: ```ini APP_NAME="Mr Bismarck" APP_ENV=production APP_DEBUG=false APP_URL=https://yourdomain.com DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=cpanelusername_mrbismarck DB_USERNAME=cpanelusername_dbuser DB_PASSWORD=your_db_password SESSION_DRIVER=database QUEUE_CONNECTION=database CACHE_STORE=database ``` > 💡 **No Redis on shared hosting?** Set `QUEUE_CONNECTION=database`, > `CACHE_STORE=database`, `SESSION_DRIVER=database` instead of `redis`. > Horizon requires Redis — if you don't have it, skip Horizon entirely > (queues will still work via the database driver + cron, see Section 6). Leave payment gateway / OpenAI / Firebase keys blank for now if you're just testing — the app will run fine, those integrations simply won't be reachable until configured. --- ## 4. Install dependencies & generate key ```bash cd ~/mrbismarck composer install --no-dev --optimize-autoloader php artisan key:generate ``` If `composer` isn't found, try `php8.3 /usr/local/bin/composer` or install it per your host's docs (cPanel → Terminal → `which composer`). --- ## 5. Build the database **Option A — fresh migrate + full demo data (recommended):** ```bash php artisan migrate --seed ``` This creates all 38 application tables + Sanctum/Spatie/queue tables, then seeds: - 955 users (1 super admin, 3 country directors, 1 finance manager, 100 drivers, 50 vendors, 800 customers) - 100 restaurants with full menus - 200 products across 6 categories - 200 jobs + 100 freelance gigs - 200 properties - 100 hotels + 50 tours - Sample rides **Option B — import the SQL file manually (no demo data):** If `php artisan migrate` fails for any reason, import `database/sql/mrbismarck_schema.sql` via phpMyAdmin (Import tab) against the empty database you created in cPanel. This creates the schema + roles/ permissions only. You can then run `php artisan db:seed` separately if PHP CLI works, to add demo data on top. --- ## 6. Final setup steps ```bash php artisan storage:link php artisan config:cache php artisan route:cache chmod -R 775 storage bootstrap/cache ``` **Queue worker (for payment webhooks, notifications, AI scoring jobs):** Since Horizon needs Redis + a persistent process (often unavailable on shared hosting), set up a **cron job** instead: cPanel → Cron Jobs → Add New Cron Job: ``` * * * * * cd /home/cpanelusername/mrbismarck && php artisan schedule:run >> /dev/null 2>&1 ``` And run the queue worker via cron every minute (processes a batch then exits — good enough for testing): ``` * * * * * cd /home/cpanelusername/mrbismarck && timeout 50 php artisan queue:work --stop-when-empty >> /dev/null 2>&1 ``` --- ## 7. Test it Visit: ``` https://yourdomain.com/api/v1/auth/login ``` (should return a JSON validation error — that means routing works ✅) Login with the seeded super admin: ``` POST /api/v1/auth/login { "phone": "254700000001", "password": "Password@123" } ``` --- ## 8. No-SSH fallback (last resort) If your host genuinely gives you no terminal/SSH/Composer: 1. Ask support to enable **SSH Access** and **Composer** — most cPanel hosts (Namecheap, Hostinger, A2, etc.) support this on request even on shared plans. 2. If truly impossible, you'll need to run `composer install` on your local machine (or this sandbox) and **upload the entire `vendor/` folder** (~150-300MB) via FTP — slow but works. Then import `database/sql/mrbismarck_schema.sql` via phpMyAdmin for the schema, run `php artisan key:generate` if you have *any* CLI access (even a "Run PHP Script" cPanel feature), or generate a 32-byte base64 key locally and set `APP_KEY=base64:...` directly in `.env`. 3. Demo data (seeders) **require PHP CLI** — without it you'll have an empty but functional schema (use Option B above + register your own test user via `/api/v1/auth/register`). --- ## 9. Troubleshooting | Symptom | Fix | |---|---| | 500 error, blank page | Set `APP_DEBUG=true` temporarily, check `storage/logs/laravel.log` | | "could not find driver" | Enable `pdo_mysql` in MultiPHP INI Editor | | 403 / "Forbidden" on all routes | Check `public/.htaccess` exists and `mod_rewrite` is enabled | | Migrations fail on FULLTEXT index | Your MySQL must be 5.7+/MariaDB 10.2+ with InnoDB fulltext support (most cPanel hosts since ~2018 are fine) | | Storage/log permission errors | `chmod -R 775 storage bootstrap/cache` | | Queue jobs never run | Set up the cron jobs in Section 6 | --- Default login after seeding: **`254700000001`** / **`Password@123`** (super admin — change this immediately on a public-facing deployment!)