================================================================================
  MULTI LANDING PAGE CMS — NAMECHEAP SHARED HOSTING DEPLOYMENT GUIDE
  Version 1.0.0  |  Last Updated: October 2025
================================================================================

  This guide covers deployment on Namecheap shared hosting (EasyWP excluded).
  All steps use the cPanel interface — no SSH or command line required.

================================================================================
  BEFORE YOU START — WHAT YOU NEED
================================================================================

  ✓ Namecheap shared hosting account with cPanel access
  ✓ A domain name pointed to Namecheap nameservers
  ✓ The MultiLandingCMS-v1.0.0-FINAL.zip file (this package)
  ✓ About 30 minutes

================================================================================
  STEP 1 — SET PHP VERSION TO 8.2 OR HIGHER
================================================================================

  1. Log in to your Namecheap cPanel
     URL: https://cpanel.yourdomain.com  OR  login via Namecheap dashboard

  2. In cPanel, scroll down to the "Software" section
     Click: "Select PHP Version"  (also called "MultiPHP Manager" on some plans)

  3. From the PHP version dropdown, select:
     PHP 8.2  (or 8.3 / 8.4 if available)

  4. Click "Set as current"

  5. IMPORTANT — Enable the sodium extension:
     While still on the PHP version page, click "Extensions" tab (or "PHP Extensions")
     Find "sodium" in the list and tick the checkbox to enable it
     Also confirm these are enabled (most are on by default):
       ✓ pdo_mysql
       ✓ mbstring
       ✓ openssl
       ✓ fileinfo
       ✓ curl
       ✓ xml
       ✓ sodium   ← REQUIRED for license system

  6. Click "Save" at the bottom

  ⚠️  If you cannot find "Select PHP Version" in your cPanel, go to:
      Namecheap Dashboard → Hosting → Manage → cPanel
      Then look under Software → MultiPHP Manager

================================================================================
  STEP 2 — CREATE THE MYSQL DATABASE
================================================================================

  1. In cPanel, find "MySQL Databases" (under Databases section)
     Click it

  2. Create a new database:
     - In the "New Database" field, type a name (e.g., cms_db)
     - Click "Create Database"
     - Note the FULL database name shown (e.g., yourusername_cms_db)

  3. Create a database user:
     - Scroll down to "MySQL Users"
     - Username: cms_user  (or any name you like)
     - Password: use a strong password — click "Generate Password" if needed
     - Click "Create User"
     - NOTE DOWN: username (e.g., yourusername_cms_user) and the password

  4. Add the user to the database:
     - Scroll to "Add User to Database"
     - User: select the user you just created
     - Database: select the database you just created
     - Click "Add"
     - On the next screen, click "ALL PRIVILEGES"
     - Click "Make Changes"

  5. Note down these 4 values — you will need them during installation:
     - DB_HOST:     localhost
     - DB_DATABASE: yourusername_cms_db    (full name shown in cPanel)
     - DB_USERNAME: yourusername_cms_user  (full name shown in cPanel)
     - DB_PASSWORD: (the password you set)

================================================================================
  STEP 3 — UPLOAD AND ARRANGE FILES
================================================================================

  Namecheap shared hosting serves your website from the public_html folder.
  Laravel requires a specific file arrangement to work securely:
  - Application code goes OUTSIDE or alongside public_html
  - Only the "public" folder contents go INSIDE public_html

  ─────────────────────────────────────────────────
  OPTION A — ROOT DOMAIN (yourdomain.com) — RECOMMENDED
  ─────────────────────────────────────────────────

  a) In cPanel, open "File Manager"
     Navigate to the root of your account (one level ABOVE public_html)
     This is usually shown as /home/yourusername/

  b) Click "Upload" at the top of File Manager
     Upload the file: MultiLandingCMS-v1.0.0-FINAL.zip
     Wait for upload to complete (16 MB — takes 1–3 minutes)

  c) Right-click the zip → Extract
     Extract location: /home/yourusername/
     This creates a folder: /home/yourusername/MultiLandingCMS-v1.0.0-FINAL/

  d) Inside that extracted folder, open the "cms" folder.
     You will see: app/, config/, database/, public/, resources/, etc.

  e) Select ALL items INSIDE the cms/ folder EXCEPT the "public" folder
     (select app, bootstrap, config, database, license-generator,
      resources, routes, storage, tests, vendor, .env.example,
      artisan, composer.json, composer.lock, etc.)
     Move them to: /home/yourusername/cms_app/
     (Create the cms_app folder first via New Folder button)

  f) Now go into cms/public/ folder
     Select ALL items inside it (.htaccess, index.php, favicon.ico, robots.txt)
     Move them to: /home/yourusername/public_html/
     (If asked to overwrite existing index.php, choose YES)

  g) Edit the file /home/yourusername/public_html/index.php
     Click the file → Edit (top toolbar)

     Find this line (around line 18):
       require __DIR__.'/../vendor/autoload.php';
     Change it to:
       require __DIR__.'/../cms_app/vendor/autoload.php';

     Find this line (around line 24):
       $app = require_once __DIR__.'/../bootstrap/app.php';
     Change it to:
       $app = require_once __DIR__.'/../cms_app/bootstrap/app.php';

     Click "Save Changes"

  ─────────────────────────────────────────────────
  OPTION B — ADDON DOMAIN OR SUBDOMAIN
  ─────────────────────────────────────────────────

  If this CMS is going on an addon domain (e.g., cms.yourdomain.com or
  anotherdomain.com added to your hosting):

  a) In cPanel → Domains → Addon Domains (or Subdomains)
     Create the domain/subdomain
     Set the Document Root to: public_html/cms/public
     (Namecheap may not allow you to set a custom root directly —
      if not, use Option A structure above but in the addon domain's folder)

  b) Upload the zip to /home/yourusername/public_html/cms_root/
     Extract it there
     The cms/public/ folder will automatically be the document root

  c) Edit index.php in cms/public/ — paths will already be correct
     (no changes needed if the full cms/ folder is in place)

================================================================================
  STEP 4 — CREATE THE .env FILE
================================================================================

  1. In File Manager, navigate to your cms_app folder
     (e.g., /home/yourusername/cms_app/)

  2. Find the file: .env.example
     Right-click → Copy → copy it in the same folder
     Rename the copy to: .env

  3. Right-click .env → Edit

  4. Fill in the following values:

     APP_NAME="Your Business Name CMS"
     APP_ENV=production
     APP_DEBUG=false
     APP_URL=https://yourdomain.com

     DB_CONNECTION=mysql
     DB_HOST=localhost
     DB_PORT=3306
     DB_DATABASE=yourusername_cms_db
     DB_USERNAME=yourusername_cms_user
     DB_PASSWORD=YourDatabasePassword

     SESSION_DRIVER=file
     CACHE_STORE=file
     QUEUE_CONNECTION=sync

  5. Leave all other values as-is for now
     Click "Save Changes"

  ⚠️  Make sure APP_URL exactly matches your domain, including https:// or http://
  ⚠️  The DB_DATABASE and DB_USERNAME must include your cPanel username prefix
      (Namecheap adds it automatically — check the exact names you noted in Step 2)

================================================================================
  STEP 5 — SET FOLDER PERMISSIONS
================================================================================

  1. In File Manager, navigate to your cms_app/ folder

  2. Right-click the "storage" folder → Change Permissions
     Set to: 755 → tick all boxes for owner, group read/execute
     Also tick write for owner
     Effectively: 755 (or use 775 if 755 doesn't work)

  3. IMPORTANT — also set permissions on these subfolders of storage/:
     - storage/app/              → 755
     - storage/app/public/       → 755
     - storage/framework/        → 755
     - storage/framework/cache/  → 755
     - storage/framework/sessions/ → 755
     - storage/framework/views/  → 755
     - storage/logs/             → 755

  4. Also set: bootstrap/cache/ → 755

  TIP: In Namecheap File Manager, you can select the storage folder
       and use "Change Permissions" → check "Apply to subdirectories and files"
       Set files to 644 and directories to 755

================================================================================
  STEP 6 — RUN THE WEB INSTALLER
================================================================================

  Open your browser and visit:
    https://yourdomain.com/install

  You will see the Multi Landing CMS Installer. Follow these steps:

  ── Page 1: Welcome ──
  Click "Start Installation"

  ── Page 2: Requirements Check ──
  You will see a checklist of PHP extensions.
  ALL items must show a green checkmark.
  If "Sodium Extension" shows red:
    → Go back to cPanel → Select PHP Version → Extensions → enable sodium → Save
    → Refresh this page
  If "Storage Writable" shows red:
    → Go back to Step 5 and fix permissions on storage/ folder

  ── Page 3: Database Configuration ──
  Enter the database details from Step 2:
    Host:     localhost
    Port:     3306
    Database: yourusername_cms_db
    Username: yourusername_cms_user
    Password: YourDatabasePassword

  Click "Test Connection"
  You should see: "Database connection successful!"
  Then click "Next"

  ── Page 4: Application Setup ──
  Fill in:
    Application Name: your business or site name
    Application URL:  https://yourdomain.com  (no trailing slash)
    Timezone:         America/New_York  (or your local timezone)

    Admin Name:     your name
    Admin Email:    your@email.com
    Admin Password: create a strong password (8+ characters)
    Confirm Password: repeat the password

    License Key: leave blank for now (upload license after install)

  Click "Install Now"

  ── Installation Progress ──
  The installer will:
    ✓ Create all database tables (migrations)
    ✓ Install all 15 landing pages with full content
    ✓ Install all 150 blog articles
    ✓ Install all 60 legal documents
    ✓ Create your admin account
    ✓ Configure the application

  This takes 30–90 seconds. Do NOT close the browser.

  ── Page 5: Complete ──
  You will see "Installation Successful!"
  Click "Go to Admin Panel"

================================================================================
  STEP 7 — LOG IN AND VERIFY
================================================================================

  1. Go to: https://yourdomain.com/admin
     Login with the email and password you set in Step 6

  2. You should see the Dashboard with:
     - 15 Landing Pages
     - 150 Blog Articles
     - 0 Enquiries (fresh install)

  3. Go to: Landing Pages → find any page → click "Set as Homepage"
     Now visit https://yourdomain.com — your homepage should load

  4. Test the contact form — submit a test enquiry
     Then check Admin → Enquiry Inbox — it should appear

================================================================================
  STEP 8 — UPLOAD THE LICENSE
================================================================================

  1. On your LOCAL computer, run the license generator:
     Open Command Prompt or Terminal, navigate to the license-generator/ folder:
       cd path\to\license-generator
       php generate.php

     This creates a license.json file.
     ⚠️  Keep the private key (private_key.hex) backed up safely.
         NEVER upload private_key.hex to your server.

  2. In the CMS Admin Panel:
     Go to: Admin → License Manager → Upload License
     Upload the license.json file

  3. The license status should change to "Active"

================================================================================
  STEP 9 — CONFIGURE EMAIL NOTIFICATIONS (OPTIONAL)
================================================================================

  To receive email alerts when new enquiries arrive:

  1. Admin Panel → Settings → Email Settings

  2. For Namecheap hosting email (using your hosting's mail server):
     Mail Host:        mail.yourdomain.com
     Mail Port:        587
     Mail Username:    you@yourdomain.com
     Mail Password:    your email account password
     Mail Encryption:  TLS
     Mail From Name:   Your Business Name
     Mail From Email:  you@yourdomain.com
     Admin Notify Email: you@yourdomain.com

  3. For Gmail:
     Mail Host:       smtp.gmail.com
     Mail Port:       587
     Mail Username:   youraddress@gmail.com
     Mail Password:   App Password (NOT your Gmail password)
                      → Create at: myaccount.google.com → Security → App Passwords
     Mail Encryption: TLS

  4. Click Save and send a test enquiry to verify delivery

================================================================================
  STEP 10 — CONFIGURE YOUR LANDING PAGES
================================================================================

  In the Admin Panel, configure each landing page:

  Landing Pages → select a page → click Settings:

    ✓ Phone Number    → your business phone (appears clickable on mobile)
    ✓ Email Address   → your contact email
    ✓ Physical Address → your business address
    ✓ Business Hours  → your operating hours
    ✓ WhatsApp Number → with country code (e.g., 15551234567 for US)
    ✓ Social Links    → Facebook, Instagram, LinkedIn URLs

  Landing Pages → select a page → Content:
    ✓ Edit hero headline, about section, service descriptions, FAQ answers
    ✓ Customise CTA button text and popup message

  When ready to go live with a page:
    Landing Pages → click "Publish" on the page
    Set one page as the active homepage: click "Set as Homepage"

================================================================================
  TROUBLESHOOTING — NAMECHEAP SPECIFIC
================================================================================

  PROBLEM: Website shows "Index of /" or directory listing
  SOLUTION: The public/ folder contents were not moved to public_html/
            OR the .htaccess file is missing from public_html/
            Check that .htaccess exists in public_html/ (it may be hidden —
            in File Manager enable "Show Hidden Files" from Settings menu)

  PROBLEM: White screen or "500 Internal Server Error"
  SOLUTION: Temporarily set APP_DEBUG=true in .env and reload the page
            The actual error message will appear — fix it then set back to false
            Most common causes on Namecheap:
            - Wrong paths in public_html/index.php (re-check Step 3g)
            - Sodium extension not enabled (re-check Step 1)
            - Storage folder not writable (re-check Step 5)

  PROBLEM: "No input file specified" or blank page
  SOLUTION: Check that index.php exists in public_html/
            Check that the paths in index.php point to the correct cms_app/ folder

  PROBLEM: PHP version warning during requirements check
  SOLUTION: Go to cPanel → Select PHP Version → choose 8.2 or higher → Save
            Then refresh the installer page

  PROBLEM: Database connection failed during install
  SOLUTION: Double-check DB_DATABASE and DB_USERNAME include the cPanel username
            prefix (e.g., myuser_cms_db, NOT just cms_db)
            Verify the user was added to the database with ALL PRIVILEGES (Step 2d)

  PROBLEM: Sodium extension not available
  SOLUTION: In cPanel → Select PHP Version → click "Extensions" tab
            Scroll to find "sodium" → tick it → click Save
            If sodium is NOT listed at all, contact Namecheap support:
            "Please enable the PHP sodium extension for my account"

  PROBLEM: "Page not found" on all admin URLs
  SOLUTION: The .htaccess file in public_html/ is missing or not being read
            Verify .htaccess content (show hidden files in File Manager)
            It should contain: "RewriteEngine On" and "RewriteRule ^ index.php [L]"

  PROBLEM: Images or file uploads not working
  SOLUTION: In cPanel File Manager, navigate to cms_app/storage/app/public/
            Check that it exists and is writable (755)
            If missing, create it manually via File Manager → New Folder

  PROBLEM: Sessions keep expiring / login loops
  SOLUTION: In .env set:
              SESSION_DRIVER=file
            Verify storage/framework/sessions/ folder exists and is writable
            Also confirm APP_URL in .env exactly matches your site URL

  PROBLEM: SSL / https not working
  SOLUTION: In Namecheap cPanel → SSL/TLS Status → check your domain
            For a free SSL: cPanel → Let's Encrypt (or AutoSSL) → Issue
            Once SSL is active, update .env: APP_URL=https://yourdomain.com

================================================================================
  FILE STRUCTURE REFERENCE
================================================================================

  After deployment, your server should look like this:

  /home/yourusername/
  ├── public_html/                ← your website root (domain points here)
  │   ├── .htaccess               ← moved from cms/public/
  │   ├── index.php               ← moved from cms/public/ (paths edited)
  │   ├── favicon.ico
  │   └── robots.txt
  │
  └── cms_app/                    ← application code (private, not web-accessible)
      ├── app/
      ├── bootstrap/
      ├── config/
      ├── database/
      ├── resources/
      ├── routes/
      ├── storage/
      ├── vendor/
      └── .env                    ← your environment config (keep private)

  license-generator/              ← keep on your LOCAL computer only
  DEPLOYMENT_GUIDE.txt            ← this file

================================================================================
  ADMIN PANEL QUICK REFERENCE
================================================================================

  Admin URL      : https://yourdomain.com/admin
  Installer URL  : https://yourdomain.com/install  (blocked after install)

  MAIN SECTIONS:
  ─────────────
  Dashboard          → Overview stats and recent activity
  Landing Pages      → Manage all 15 pages (publish, configure, set homepage)
  Blog Articles      → Manage 150 articles across all pages
  Blog Categories    → Manage categories per page
  Enquiry Inbox      → All contact form submissions (filter, note, export)
  Users              → Staff accounts and role assignments
  Settings           → App settings, SMTP, reCAPTCHA
  Backup Manager     → Create and restore database backups
  Update Manager     → Apply platform updates
  License Manager    → Upload and verify license

  STAFF ROLES:
  ────────────
  super_admin      → Full access to everything
  admin            → All content and user management
  content_manager  → Blog and page content editing only
  enquiry_manager  → Enquiry inbox management only
  read_only        → View-only access

================================================================================
  SECURITY REMINDERS
================================================================================

  ✓ APP_DEBUG must be false on production (hides error details from visitors)
  ✓ Keep your .env file permissions set to 644 (readable, not world-writable)
  ✓ The license private_key.hex must NEVER be uploaded to the server
  ✓ Use a strong admin password — at least 12 characters
  ✓ Download a database backup monthly via Admin → Backup Manager
  ✓ The /install URL is automatically blocked once installation is complete
  ✓ Enable SSL/HTTPS on your domain (free via Namecheap AutoSSL in cPanel)

================================================================================
  NEED HELP?
================================================================================

  Namecheap cPanel Login:
    https://www.namecheap.com/myaccount/login/

  Namecheap Live Chat Support (24/7):
    https://www.namecheap.com/support/

  Common Namecheap cPanel locations:
    PHP Version:     Software → Select PHP Version
    File Manager:    Files → File Manager
    MySQL Databases: Databases → MySQL Databases
    SSL:             Security → SSL/TLS Status

================================================================================
  END OF DEPLOYMENT GUIDE
================================================================================
