ProposalTrack — cPanel Installation Guide

Overview

This guide walks you through installing ProposalTrack on cPanel-based shared hosting in about 10 minutes — no SSH or command line required.

cPanel is the most common hosting control panel, used by providers like Namecheap, Bluehost, HostGator, SiteGround, A2 Hosting, GoDaddy, and many others. The screenshots and menu names in this guide refer to cPanel's standard layout.

Hosting Requirements

Required PHP Extensions

Most cPanel hosts have all of these enabled by default:

• pdo_mysql, openssl, mbstring, tokenizer
• xml, ctype, json, bcmath, fileinfo

What to Prepare

Before starting, have these ready:

• Your cPanel login URL (usually yourdomain.com/cpanel or yourdomain.com:2083)
• cPanel username and password
• The ProposalTrack ZIP file from Codester
• An email address you'll use as the admin account
• SMTP credentials for sending email (optional, can be configured later)

Step 1 — Set PHP Version to 8.2 or Higher

1. Log in to cPanel Go to your hosting login URL and sign in.
2. Find "Select PHP Version" or "MultiPHP Manager" cPanel Home → Software → Select PHP Version
3. Choose PHP 8.2 or 8.3 From the version dropdown, select 8.2 or higher and click Set as current.
4. Enable required extensions On the same page, click the Extensions tab and ensure these are checked:
   • pdo_mysql · openssl · mbstring
   • tokenizer · xml · ctype
   • json · bcmath · fileinfo
5. Save changes Click Save.

Step 2 — Upload the ZIP File

1. Open File Manager cPanel Home → Files → File Manager
2. Navigate to the destination folder For your main domain: open public_html. For a subdomain or subfolder, see the Subdomain section.
3. Upload the ZIP Click Upload in the top toolbar. Drag your proposaltrack.zip file into the upload area and wait for it to reach 100%.
4. Return to File Manager Once upload is complete, click Go Back to /home/.../public_html.

Step 3 — Extract the Files

1. Right-click the ZIP file In File Manager, right-click proposaltrack.zip and select Extract.
2. Confirm extraction path The path should be your current folder (e.g. /home/username/public_html). Click Extract Files.
3. Verify the structure You should see folders like app/, config/, public/, storage/, vendor/, plus files like index.php, .htaccess, and .env.example.
4. (Optional) Delete the ZIP Once extraction is confirmed, delete proposaltrack.zip to save disk space.

Step 4 — Create a MySQL Database

1. Open MySQL Database Wizard cPanel Home → Databases → MySQL Database Wizard
2. Create a database Enter a name like proposaltrack. cPanel will prefix it automatically (e.g. username_proposaltrack). Write down the full prefixed name. Click Next Step.
3. Create a database user Enter a username (e.g. ptadmin) — also auto-prefixed (e.g. username_ptadmin). Click the Password Generator for a strong password and copy it somewhere safe. Click Create User.
4. Assign user to database On the next screen, check ALL PRIVILEGES, then click Next Step.
5. Save these three values You'll need them in step 7:
   • Database name: e.g. username_proposaltrack
   • Database user: e.g. username_ptadmin
   • Database password: (whatever you generated)
   • Host: localhost (works for 99% of cPanel hosts)

Step 5 — Set Folder Permissions

ProposalTrack needs to write to a few folders. Most cPanel hosts already use the correct permissions, but it's worth verifying.

1. Open File Manager Navigate to your installation folder (e.g. public_html).
2. Right-click storage → Change Permissions Set to 755 and check Recurse into subdirectories. Click Change Permissions.
3. Repeat for bootstrap/cache Set the bootstrap/cache folder to 755 as well.
4. If your host uses suPHP or LSAPI 755 is correct. If you see permission errors later, try 775 or contact your host.

Step 6 — Configure the .env File

1. Show hidden files In File Manager → top-right → Settings → check Show Hidden Files.
2. Locate .env.example Right-click it and choose Rename. Rename to .env.
3. Edit .env Right-click .env → Edit. If a popup asks about character encoding, click Edit again to confirm.
4. Update these values

   APP_NAME=ProposalTrack
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com
   
   SESSION_DRIVER=file
   CACHE_STORE=file
   QUEUE_CONNECTION=sync

   Important: SESSION_DRIVER and CACHE_STORE must be file (not database) — otherwise the installer will crash with a session error before you can configure the DB.
5. Save Click Save Changes in the top-right.

Step 7 — Run the Web Installer

1. Open your domain in the browser Visit https://yourdomain.com/. You'll be redirected automatically to /install.
2. Step 1 — Requirements check The installer verifies PHP version, extensions, and folder permissions. All items should be green. If any are red, fix them (usually a PHP version or extension issue from Step 1) and reload. Click Continue.
3. Step 2 — Database Enter the values you saved in Step 4:
   • Host: localhost
   • Port: 3306
   • Database name: username_proposaltrack
   • Username: username_ptadmin
   • Password: (your generated password)
   Click Test & Migrate. The installer connects to MySQL and creates all tables.
4. Step 3 — Admin account Set your admin email, name, and password. Use a strong password — at least 12 characters with mixed case, numbers, and symbols.
5. Step 4 — Site settings Enter your site name (e.g. "My Proposals") and a contact email. Both can be changed later in the admin panel.
6. Step 5 — Done! The installer shows a success message and locks itself. Click Go to Admin Panel.

Step 8 — Verify Your Installation

• Visit https://yourdomain.com/ — the public upload form loads
• Visit https://yourdomain.com/admin/login and log in successfully
• Admin dashboard loads without errors
• Visit Settings → Email, configure SMTP, and click Send Test Email
• Upload a test proposal from the homepage
• Open the share link in an incognito window — view is tracked in the admin panel
• Configure the cron job (see below)
• Install SSL if not already active (see below)

Install on a Subdomain

Want to run ProposalTrack at proposals.yourdomain.com instead of the main domain?

1. Create the subdomain cPanel → Domains → Subdomains Enter proposals as the prefix and select your main domain. cPanel auto-creates a folder like public_html/proposals.
2. Upload & extract files there In Step 2, navigate to public_html/proposals instead of public_html. Then continue normally from Step 3.
3. Update APP_URL In .env, set APP_URL=https://proposals.yourdomain.com.

Install in a Subfolder

To install at yourdomain.com/proposals (under an existing main site):

1. Create the folder: in File Manager, inside public_html, create proposals.
2. Upload & extract the ZIP into public_html/proposals.
3. In .env, set APP_URL=https://yourdomain.com/proposals.
4. Run the installer at https://yourdomain.com/proposals/install.

Install Free SSL Certificate

Most cPanel hosts include free Let's Encrypt SSL.

1. Open SSL/TLS Status cPanel → Security → SSL/TLS Status
2. Select your domain & "Run AutoSSL" Click Run AutoSSL. Wait 1-5 minutes.
3. Force HTTPS Open .htaccess in your domain root and add at the top (after RewriteEngine On):

   RewriteCond %{HTTPS} off
   RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

4. Update APP_URL Change APP_URL=http://... to APP_URL=https://... in .env.

Setup the Cron Job (Optional)

Cleans up expired OTP records once a day. Not strictly required but recommended.

1. Open Cron Jobs cPanel → Advanced → Cron Jobs
2. Add a new cron job Set the schedule to Once Per Minute (or use * * * * *).
3. Enter the command Replace username with your cPanel username:

   cd /home/username/public_html && /usr/local/bin/php artisan schedule:run >> /dev/null 2>&1

4. Save Click Add New Cron Job.

Use cPanel Email (SMTP)

If you've created an email account in cPanel (like noreply@yourdomain.com), use it as the SMTP server:

1. Create an email account cPanel → Email → Email Accounts → Create Use something like noreply@yourdomain.com.
2. Get connection settings On the email account, click Connect Devices. Look for the "Mail Client Manual Settings".
3. Configure ProposalTrack In the admin panel → Settings → Email:

   Host	mail.yourdomain.com
   Port	465 (SSL) or 587 (TLS)
   Encryption	ssl or tls
   Username	noreply@yourdomain.com (full email)
   Password	your email password
   From address	noreply@yourdomain.com

4. Test it Click Send Test Email.

Backup Your Site

Always backup before upgrades or major changes.

1. Open Backup Wizard cPanel → Files → Backup Wizard
2. Click Backup → Full Backup Choose Home Directory destination, enter your email for notification, click Generate Backup.
3. Download to your computer When complete, download the .tar.gz file via File Manager.
4. Backup just the database Alternatively: cPanel → phpMyAdmin → select your database → Export → Quick / SQL.

500 Internal Server Error

The most common error on cPanel installs. Causes, in order of likelihood:

1. PHP version is too old

Go to Select PHP Version and confirm 8.2 or higher is selected. If your host doesn't offer 8.2+, contact them or switch hosts.

2. Wrong file permissions

In File Manager, set:

• All folders: 755
• All files: 644
• storage/ and bootstrap/cache/: writable (755 or 775)

3. Missing .env file or APP_KEY

Make sure .env exists (renamed from .env.example) and contains a valid APP_KEY=base64:.... If APP_KEY is empty, you can paste a fresh one from .env.example.

4. Check the actual error

Set APP_DEBUG=true in .env temporarily, reload the page, and read the real error message. Set it back to false after debugging.

Also check storage/logs/laravel.log in File Manager for the full stack trace.

SQLSTATE[28000] / "Access denied for user 'root'"

This happens when SESSION_DRIVER=database or CACHE_STORE=database is set but the database isn't configured yet (or has wrong credentials).

Fix:

1. Open .env in File Manager
2. Change these three lines:

   SESSION_DRIVER=file
   CACHE_STORE=file
   QUEUE_CONNECTION=sync

3. Save the file
4. Reload your domain — installer will load correctly

"Permission denied" / "failed to open stream"

Laravel can't write to storage/, bootstrap/cache/, or the log files.

Fix:

1. In File Manager, right-click storage → Change Permissions
2. Set to 755, check Recurse into subdirectories, click Change Permissions
3. Repeat for bootstrap/cache
4. If still failing, try 775 instead of 755
5. If your host shows "owner mismatch" errors, contact support — they may need to fix the file ownership

Proposal Upload Fails

"File too large" or upload silently fails

1. cPanel → Select PHP Version → Options tab
2. Increase these values:
   • upload_max_filesize = 50M
   • post_max_size = 50M
   • memory_limit = 256M
   • max_execution_time = 300
3. Save
4. In ProposalTrack admin → Settings → Uploads, set max file size to match (in MB).

"File type not allowed"

Admin → Settings → Uploads → add the extension to the allowed types list (comma-separated, no dots: pdf,doc,docx,xlsx).

Blank White Page

Almost always a PHP error with output suppressed.

1. Set APP_DEBUG=true in .env
2. Reload — you should see the actual error
3. If still blank: check storage/logs/laravel.log
4. If the log is empty: cPanel → Errors (under Metrics) — look at the latest entries
5. Common causes: missing PHP extension (install via PHP Selector), low memory limit (raise to 256M), syntax error in .env

404 Not Found on Every Page Except Homepage

Apache's mod_rewrite isn't active or the .htaccess file is missing.

Check 1 — .htaccess exists

In File Manager, enable Show Hidden Files. You should see .htaccess in your domain root and inside public/. If missing, re-extract from the ZIP.

Check 2 — mod_rewrite enabled

Almost all cPanel hosts have it on by default. If you suspect otherwise, contact your host's support and ask them to enable mod_rewrite for your account.

Check 3 — AllowOverride

If .htaccess directives are ignored, your host has AllowOverride None set. Ask support to change it to AllowOverride All.

"This PHP version is not supported"

You're running PHP < 8.2.

1. cPanel → Select PHP Version
2. Switch to PHP 8.2 or 8.3
3. Click Set as current
4. Reload the page

Still Stuck?

Open a support ticket on the Codester product page with:

• Your Codester purchase ID
• Your hosting provider name
• PHP version (from cPanel → Select PHP Version)
• The exact error message you're seeing
• The last 50 lines of storage/logs/laravel.log
• A screenshot of the error if visible in the browser

We'll get back to you within 24 hours.