================================================================
 SALIHIYA WORLD CARGO — cPanel Deployment Guide
 Repository: https://github.com/Muhamaddiis/cargo-portal.git
================================================================


PHASE 1 — CONNECT TO SERVER VIA SSH
-------------------------------------
You have a .ppk key. Use PuTTY on Windows.

1. Download PuTTY from https://www.putty.org if not installed.

2. Open PuTTY:
   - Host Name : your server IP or domain
   - Port      : 22
   - Connection type: SSH

3. Load your PPK key:
   - Left panel → Connection → SSH → Auth → Credentials
   - "Private key file for authentication" → Browse → select your .ppk file

4. Click Open.
   - Login as: your_cpanel_username (same as cPanel login)
   - You should see a prompt like: [username@server ~]$


PHASE 2 — CREATE THE DATABASE (in browser at yourdomain.com/cpanel)
----------------------------------------------------------------------
1. cPanel → MySQL Databases

2. Create New Database → name it "cargo" → click Create
   (full name will be username_cargo — note it down)

3. Create New User → username: cargouser, set a strong password → Create
   (full name will be username_cargouser — note it down)

4. Add User To Database → select the user and database → All Privileges → Add

Note down:
   DB name     : username_cargo
   DB user     : username_cargouser
   DB password : what you set


PHASE 3 — SET PHP VERSION + EXTENSIONS (in browser)
------------------------------------------------------
1. cPanel → MultiPHP Manager → find your domain → set to PHP 8.2 → Apply

2. cPanel → Select PHP Version → Extensions
   Make sure these are TICKED:
     [x] zip
     [x] gd
     [x] intl
     [x] mbstring
     [x] pdo_mysql
     [x] fileinfo
     [x] openssl

3. Save.


PHASE 4 — CONFIGURE GIT ON THE SERVER (SSH)
---------------------------------------------
1. Check Git is installed:
   git --version
   (if you get "command not found", contact your host — most cPanel hosts have Git)

2. Set your identity (required for Git to work):
   git config --global user.name "Your Name"
   git config --global user.email "your@email.com"

3. Set the default branch name to match GitHub:
   git config --global init.defaultBranch main

4. Verify the config saved:
   git config --global --list
   (you should see user.name, user.email, and init.defaultBranch)


--- PRIVATE REPO: GENERATE A DEPLOY KEY ---

Because the repository is private, the server needs permission to pull from GitHub.
We do this with an SSH Deploy Key — a key generated on the server that you add to
GitHub. It gives the server read-only access to this one repo. This is the most
secure approach and never expires.

Step A — Generate the key on the server:
   ssh-keygen -t ed25519 -C "cargo-portal-server" -f ~/.ssh/cargo_deploy_key -N ""

   (This creates two files:
      ~/.ssh/cargo_deploy_key      <- private key, stays on the server
      ~/.ssh/cargo_deploy_key.pub  <- public key, goes to GitHub)

Step B — Print the public key:
   cat ~/.ssh/cargo_deploy_key.pub

   Copy the entire output — it starts with "ssh-ed25519 ..."

Step C — Add the key to GitHub (in browser):
   1. Go to https://github.com/Muhamaddiis/cargo-portal
   2. Settings → Deploy keys → Add deploy key
   3. Title: "cPanel Server"
   4. Key: paste the public key you copied
   5. Leave "Allow write access" UNTICKED (read-only is enough)
   6. Click Add key

Step D — Tell SSH on the server to use this key for GitHub:
   nano ~/.ssh/config

   Paste this block:
   ------------------------------------------------
   Host github.com
       HostName github.com
       User git
       IdentityFile ~/.ssh/cargo_deploy_key
       IdentitiesOnly yes
   ------------------------------------------------
   Save: Ctrl+O → Enter → Ctrl+X

Step E — Test the connection:
   ssh -T git@github.com

   You should see:
   "Hi Muhamaddiis/cargo-portal! You've successfully authenticated..."

Note: The server only ever PULLS — all pushes happen from your local machine.


PHASE 5 — CLONE THE REPO (SSH)
--------------------------------
cd ~
mkdir -p clients
cd clients

git clone git@github.com:Muhamaddiis/cargo-portal.git salihiya
   (uses the deploy key — no password prompt)

cd salihiya
ls
   (you should see app/ composer.json public/ etc.)


PHASE 6 — INSTALL DEPENDENCIES (SSH)
--------------------------------------
composer --version
   (if not found, run these two lines:)
   curl -sS https://getcomposer.org/installer | php
   mv composer.phar /usr/local/bin/composer

composer install --no-dev --optimize-autoloader
   (takes 1-2 minutes)


PHASE 7 — CONFIGURE .ENV FILE (SSH)
-------------------------------------
cp .env.example .env
nano .env

Fill in these values:

   APP_NAME="Salihiya World Cargo"
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com

   DB_CONNECTION=mysql
   DB_HOST=localhost
   DB_PORT=3306
   DB_DATABASE=username_cargo        <- from Phase 2
   DB_USERNAME=username_cargouser    <- from Phase 2
   DB_PASSWORD=yourpassword          <- from Phase 2

   SESSION_SECURE_COOKIE=true        <- requires HTTPS (enable SSL in cPanel first)

Save and exit: Ctrl+O → Enter → Ctrl+X


PHASE 8 — RUN SETUP COMMANDS (SSH)
-------------------------------------
Run these one by one:

   php artisan key:generate
   php artisan migrate --force
   php artisan db:seed --force
   cd public && ln -s ../storage/app/public storage && cd ..
   (Note: php artisan storage:link is disabled on shared hosting — use ln -s instead)
   chmod -R 775 storage bootstrap/cache
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   php artisan filament:optimize


PHASE 9 — POINT DOMAIN TO public/ (in browser)
-------------------------------------------------
1. cPanel → Domains → find your domain → Manage
2. Change Document Root to:
      /home/username/clients/salihiya/public
3. Save.


PHASE 10 — SET UP THE DEPLOY SCRIPT (SSH)
------------------------------------------
cp ~/clients/salihiya/deploy.sh ~/clients/deploy.sh
chmod +x ~/clients/deploy.sh


PHASE 11 — FIRST LOGIN TEST
------------------------------
Open browser → https://yourdomain.com
Should redirect to /admin/staff-login

First login credentials:
   Email    : superadmin@cargo.com
   Password : changeme123

IMPORTANT: Change the password immediately after logging in.
   Administration → Staff Accounts → Edit Super Admin → set new password

================================================================
 FUTURE UPDATES (3 commands from your local machine)
================================================================
git pull origin main
php artisan migrate
php artisan optimize:clear

1. Push your changes to GitHub:
   git push origin main

2. SSH into the server:
   ssh username@yourserver.com

3. Deploy:
   ./clients/deploy.sh salihiya


================================================================
 ONBOARDING A SECOND CLIENT
================================================================

On the server (SSH):
   cd ~/clients
   git clone git@github.com:Muhamaddiis/cargo-portal.git clientname
   cd clientname
   composer install --no-dev --optimize-autoloader
   cp .env.example .env
   nano .env          <- fill in new client's DB, APP_NAME, APP_URL
   php artisan key:generate
   php artisan migrate --force
   php artisan db:seed --force
   cd public && ln -s ../storage/app/public storage && cd ..
   (Note: php artisan storage:link is disabled on shared hosting — use ln -s instead)
   chmod -R 775 storage bootstrap/cache
   php artisan config:cache && php artisan route:cache
   php artisan view:cache && php artisan filament:optimize

In cPanel:
   - Point new domain document root to /home/username/clients/clientname/public
   - Enable SSL (Let's Encrypt in cPanel)

Time to onboard: ~15 minutes.


================================================================
 TROUBLESHOOTING
================================================================

White screen / 500 error:
   - Check: cat storage/logs/laravel.log | tail -50
   - Make sure APP_DEBUG=false and APP_KEY is set in .env

Permission denied errors:
   - chmod -R 775 storage bootstrap/cache

Migrations fail:
   - Double-check DB_DATABASE, DB_USERNAME, DB_PASSWORD in .env
   - Verify the DB user has ALL PRIVILEGES on the database

Memory exhausted:
   - Verify PHP memory_limit is 512M in cPanel MultiPHP INI Editor

Excel import not working:
   - Verify zip and gd extensions are enabled in cPanel PHP Extensions

composer: command not found:
   - curl -sS https://getcomposer.org/installer | php
   - mv composer.phar /usr/local/bin/composer

git pull asks for username/password or permission denied:
   - The deploy key may not be set up yet — complete Phase 4 steps A-E
   - Test with: ssh -T git@github.com
   - Make sure ~/.ssh/config has the correct IdentityFile path
   - Fix the remote URL to use SSH (not HTTPS):
     git remote set-url origin git@github.com:Muhamaddiis/cargo-portal.git

================================================================
