cPanel deployment walkthrough

This walkthrough installs Zodiac Tech CRM on shared cPanel hosting (the production target: https://crm.zodiactechsoft.in). It uses the browser installer — the same flow buyers use — and documents the manual artisan equivalents for hosts with Terminal access.

Who this is for#

• Super-admin / hosting admin — doing the first install.
• Developer — reproducing a customer's install problem.

Prerequisites:

• cPanel login that can create subdomains, databases, cron jobs and set PHP versions.
• The release zip of the application (or the project folder from your source).
• ~30–60 minutes.

Step 1 — Create the subdomain#

1. cPanel → Domains → Create A New Domain (older panels: Subdomains).

2. Enter crm for crm.zodiactechsoft.in (adjust to your domain).

3. Document Root — type the folder where the app will live, ending in /public, for example:

   /home/YOURUSER/crm-app/public
   

   If cPanel forces public_html/crm as the root and you cannot change it, that is fine — you are now in the fallback layout; keep reading, Steps 6–7 cover it.

4. Create.

Expected result: the subdomain resolves (it may 403/404 until files exist).

Step 2 — Set the PHP version#

1. cPanel → MultiPHP Manager → select the subdomain → PHP 8.4.
2. cPanel → Select PHP Version → Extensions (or MultiPHP INI Editor) and confirm the required extensions are enabled: pdo_mysql, mbstring, zip, gd, curl, bcmath, fileinfo, intl if offered.

Expected result: PHP 8.4 is active for the domain. (php -v in cPanel Terminal should also say 8.4 if you have terminal.)

Step 3 — Upload the application#

Everything lives in one app folder. Upload it to the folder above your document root (e.g. /home/YOURUSER/), so the layout becomes /home/YOURUSER/crm-app/….

3a — What must be in the package#

3b — What to leave out#

3c — Upload mechanics#

1. cPanel → File Manager → navigate to the folder above your document root.
2. Upload the package zip, then select it → Extract.
3. Confirm the structure: crm-app/app/, crm-app/public/, crm-app/vendor/, crm-app/index.php, and crm-app/.htaccess (hidden files on).

If you have Terminal and prefer git/uploads without a zip:

cd ~/crm-app   # or wherever the app will live
# upload via your preferred method, then:
php -v         # confirm 8.4

Step 4 — Prepare dependencies and write permissions#

With Terminal (Composer 2 available):

cd ~/crm-app
composer install --no-dev --optimize-autoloader

The post-autoload-dump scripts automatically run artisan package:discover and artisan filament:upgrade, so Filament's assets and caches are wired correctly.

Without Terminal (typical shared hosting): skip composer install — upload the vendor/ folder from your build machine as part of the zip, or via FTP/File Manager. A vendor/ built by the same PHP version line is required (PHP 8.4).

Then make the app writable. In File Manager, set:

• storage/ — recursively, permission 775
• bootstrap/cache/ — 775
• public/ — 775 (writes per-tenant branding CSS into public/tenant/<id>/ on settings save)

# Terminal equivalent
chmod -R 775 storage bootstrap/cache public

Step 5 — Create the database#

1. cPanel → MySQL Databases.
2. Create database YOURUSER_leadhub and a dedicated user with a strong password.
3. Add the user to the database with ALL PRIVILEGES.

Expected result: you have four values ready for the next step: host (localhost), database name, username, password.

Full detail (including utf8mb4 and migration options): Database setup & migrations.

Step 6 — Run the browser installer#

1. Open in a browser:

   https://crm.zodiactechsoft.in/install.php
   

   If storage/installed.lock does not exist yet, even hitting / bounces you here automatically.

2. Step 1 — Requirements: PHP 8.4.1+, extensions, writable folders. Fix anything red.

3. Step 2 — Database: enter the credentials from Step 5 (host, port, database, user, password). The installer tests the connection before continuing.

4. Step 3 — Admin: create your first admin login (name, e-mail, password).

5. Step 4 — Install: review the summary — it shows the exact APP_URL it will write to .env — and run the install. The installer writes .env and generates APP_KEY, migrates the schema, seeds base data (roles, plans, permissions, locales), creates the owner account, and writes storage/installed.lock.

Expected result: the installer writes storage/installed.lock and points you at the login page.

Step 7 — Layout check (the subfolder warning)#

If the document root points at public/ — nothing to do. https://crm.zodiactechsoft.in/ serves the app.

If you could NOT point the document root at public/ (the app root itself is the web root, e.g. /home/USER/public_html/crm/), the shipped root files handle it:

• The root .htaccess re-exports the Authorization header, blocks app|bootstrap|config|database|resources|routes|storage and dotfiles, forwards static trees from public/ (build, css, js, storage, vendor, install.php, …), and routes everything else into the root index.php.
• The root index.php requires public/index.php in a way that keeps Symfony's base-URL detection aligned with /crm — so Laravel sees /login, not /crm/login.

This mirrors the local XAMPP setup exactly (http://localhost/Lead%20Hub/ works this way). Verify after install:

https://crm.zodiactechsoft.in/crm/login      ← should load the login page

Step 8 — Common finishing commands (Terminal, optional)#

cd ~/crm-app
php artisan storage:link          # public link for uploaded files (see note)
php artisan migrate --force       # if anything is pending
php artisan optimize:clear        # clear stale compiled config/routes/views

storage:link is recommended but no longer load-bearing for the core branding flow: logo/favicon URLs are rewritten to the symlink-free /media route (app/Support/PublicMedia.php) and call recordings stream from the private disk through a signed route — neither needs the symlink. Uploaded files that still emit public /storage/... URLs (WhatsApp template media handles, Meta creative assets) do use it, so run it unless your host forbids symlinks entirely.

Step 8b — Behind Cloudflare / a proxy, and HTTPS cookie flags#

Two .env tweaks the installer cannot infer (add them and run php artisan optimize:clear):

• TRUSTED_PROXIES — if the site is behind Cloudflare or a reverse proxy (or any host that terminates TLS before PHP), set TRUSTED_PROXIES=* (or the proxy IPs, comma-separated). Without it $request->ip() is the proxy's IP — degrading login lockout, audit-log IPs, and the Super Admin IP allowlist.
• SESSION_SECURE_COOKIE=true — once the site is on HTTPS (any Let's Encrypt/cPanel SSL cert), set this so session cookies are only sent over TLS. Pair it with APP_URL=https://... — an http:// APP_URL on an HTTPS site breaks OAuth redirects and generated URLs.

Step 9 — Add the one cron entry#

cPanel → Cron Jobs → add a once-per-minute job:

* * * * * cd /home/YOURUSER/crm-app && php artisan schedule:run >> /dev/null 2>&1

On hosts where the php binary is not the 8.4 one, use the full path (cPanel shows it, e.g. /usr/local/bin/php or ea-php84):

* * * * * /usr/local/bin/ea-php84 /home/YOURUSER/crm-app/artisan schedule:run >> /dev/null 2>&1

No SSH/Terminal at all? The product ships a fallback runner:

* * * * * php /home/YOURUSER/public_html/crm/cron.php

cron.php drains queued jobs (up to 30 per run, 55 s budget) and then runs schedule:run — see Cron & queue workers.

Expected result: within a couple of minutes, queued jobs start processing and scheduled tasks appear in logs.

Step 10 — First login and go-live checks#

1. Open https://crm.zodiactechsoft.in/login (or /super-admin for the platform panel) and sign in with the owner account.
2. Confirm: /api/v1/health returns {"status":"ok",...}, the /docs portal loads, and a test e-mail sends from Settings → SMTP.
3. Work through the Go-live checklist before handing the system to anyone.

Common mistakes#

• Uploading the project folder so that public/ is buried and pointing the document root at the app root without the shipped bridge files — the fallback layout only works with the shipped root index.php + .htaccess present.
• Using http:// for APP_URL on an HTTPS site — OAuth redirects and generated URLs break.
• Running migrations via phpMyAdmin by hand instead of artisan/installer — schema stays untracked.
• Granting the DB user access to all databases instead of just the app's.
• Adding cron as schedule:run only and forgetting that queued jobs need the worker/cron drain too.

Troubleshooting#

Technical details#

• Installer: public/install.php (pure PHP; writes .env, migrates, creates owner, writes storage/installed.lock).
• Bridge files (subfolder layout): root index.php, root .htaccess; the standard layout relies on public/index.php + public/.htaccess instead.
• Database schema: database/migrations/; base data: database/seeders/DatabaseSeeder.php.
• Diagnostics: GET /api/v1/health.

Related guides#

• Server requirements
• Database setup & migrations
• Environment variables
• Domain, subdomain & SSL
• Cron & queue workers
• Go-live checklist