Agency PM — cPanel Installation Guide

Before starting, confirm your cPanel hosting plan supports the following:

Required PHP extensions

Go to cPanel → Select PHP Version → Extensions and enable:

pdo_mysql    # Database driver
mbstring     # String handling
openssl      # Encryption / JWT
tokenizer    # Laravel requirement
xml          # XML parsing
ctype        # Character type functions
fileinfo     # File validation
json         # JSON support
bcmath       # Precise arithmetic

1. Open MySQL Databases In cPanel, go to Databases → MySQL Databases
2. Create a new database Enter a name, e.g. yourusername_agencypm → click Create Database
3. Create a database user Scroll down to MySQL Users → enter username and a strong password → click Create User
4. Add user to database In the Add User to Database section, select the user and database → click Add → grant ALL PRIVILEGES → click Make Changes

The recommended setup uses two subdomains — one for the API and one for the frontend:

1. Go to Subdomains cPanel → Domains → Subdomains
2. Create API subdomain Subdomain: api · Domain: yourdomain.com · Document root: public_html/api/public → click Create
3. Create app subdomain Subdomain: app · Domain: yourdomain.com · Document root: public_html/app → click Create
4. Add SSL certificates cPanel → Security → SSL/TLS → Run AutoSSL on both subdomains for HTTPS

Folder structure on server

Upload via File Manager

1. Open File Manager cPanel → Files → File Manager → navigate to public_html/
2. Create the api folder Click + Folder → name it api
3. Zip your backend folder On your local machine, zip the entire backend/ folder contents (not the folder itself)
4. Upload the zip Inside public_html/api/ → click Upload → upload your zip file
5. Extract it Right-click the zip → Extract → confirm destination is /public_html/api/

1. Copy the example file In File Manager, navigate to public_html/api/ → find .env.example → right-click → Copy → name it .env
2. Edit the .env file Right-click .env → Edit → update all values below

# Application
APP_NAME="Agency PM"
APP_ENV=production
APP_KEY=                        # Will generate this in Step 7
APP_DEBUG=false
APP_URL=https://api.yourdomain.com

# Database — use values from Step 2
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=yourusername_agencypm
DB_USERNAME=yourusername_dbuser
DB_PASSWORD=YourStrongPassword123!

# Frontend URL (for CORS)
FRONTEND_URL=https://app.yourdomain.com
SANCTUM_STATEFUL_DOMAINS=app.yourdomain.com

# Session & Cache
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

Option A — Via SSH (recommended)

Open cPanel → Advanced → Terminal (or connect via SSH with your cPanel credentials):

# Navigate to your project
cd ~/public_html/api

# Install PHP dependencies (production mode)
composer install --no-dev --optimize-autoloader

# Generate app key
php artisan key:generate

# Set storage permissions
chmod -R 775 storage bootstrap/cache
chown -R $(whoami):$(whoami) storage bootstrap/cache

Option B — Without SSH (local vendor upload)

If your host does not provide terminal access:

1. On your local machine Open terminal in the backend/ folder → run: composer install --no-dev --optimize-autoloader
2. Generate the app key locally Run: php artisan key:generate --show → copy the output (e.g. base64:Abc123...)
3. Paste the key into .env on server Edit the .env file on the server → set APP_KEY=base64:Abc123...
4. Upload the vendor/ folder Upload the entire vendor/ folder to public_html/api/vendor/ via FTP or File Manager

Via SSH / cPanel Terminal

# Run all database migrations
php artisan migrate --force

# Open Laravel Tinker to create your admin account
php artisan tinker

Inside Tinker, paste and run:

App\Models\User::create([
    'name'     => 'Admin',
    'email'    => 'admin@youragency.com',
    'password' => bcrypt('YourStrongPassword!'),
    'role'     => 'super_admin',
]);

# Press Ctrl+D or type exit() to leave Tinker

Alternative — phpMyAdmin (no SSH)

If you have no SSH access, import migrations manually:

1. Open phpMyAdmin cPanel → Databases → phpMyAdmin → select your database
2. Create tables manually Go to the SQL tab and run the CREATE TABLE statements from the migration files in database/migrations/
3. Insert admin user In the SQL tab, run the INSERT statement below

-- Run in phpMyAdmin SQL tab
INSERT INTO users (name, email, password, role, is_active, created_at, updated_at)
VALUES (
  'Admin',
  'admin@youragency.com',
  '$2y$12$paste_bcrypt_hash_here',   -- generate at bcrypt-generator.com
  'super_admin',
  1,
  NOW(), NOW()
);

Backend — public_html/api/public/.htaccess

Laravel includes this file by default. Verify it contains:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ index.php [QSA,L]

    # Handle Authorization header (required for Sanctum tokens)
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

# Security headers
<IfModule mod_headers.c>
    Header always set X-Content-Type-Options nosniff
    Header always set X-Frame-Options DENY
    Header always set X-XSS-Protection "1; mode=block"
</IfModule>

Frontend — public_html/app/.htaccess

Create this file so React Router works correctly (all routes serve index.html):

Options -MultiViews
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # Serve existing files and folders directly
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    # Everything else goes to React's index.html
    RewriteRule ^ index.html [QSA,L]
</IfModule>

# Cache static assets
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType text/css "access plus 1 month"
    ExpiresByType application/javascript "access plus 1 month"
</IfModule>

On your local machine

# Navigate to frontend folder
cd frontend

# Create production environment file
echo 'VITE_API_URL=https://api.yourdomain.com/api/v1' > .env.production

# Install dependencies
npm install

# Build for production
npm run build

# The dist/ folder is ready to upload
ls dist/

Upload to server

1. Zip the dist/ folder contents Select everything inside dist/ (not the folder itself) → zip it
2. Upload to public_html/app/ In File Manager, navigate to public_html/app/ → Upload the zip file
3. Extract the zip Right-click the zip → Extract → confirm public_html/app/ as destination
4. Create the .htaccess file In public_html/app/ → New File → name it .htaccess → paste the contents from Step 8

Laravel must allow requests from your React frontend domain. Open public_html/api/config/cors.php and update:

<?php

return [
    'paths'             => ['api/*'],
    'allowed_methods'   => ['*'],
    'allowed_origins'   => [
        'https://app.yourdomain.com',
    ],
    'allowed_origins_patterns' => [],
    'allowed_headers'   => ['*'],
    'exposed_headers'   => [],
    'max_age'           => 0,
    'supports_credentials' => false,
];

Also ensure Sanctum is configured in config/sanctum.php:

'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'app.yourdomain.com'
)),

Clear the config cache after making changes:

php artisan config:clear
php artisan cache:clear

Test the API

Open your browser or use a tool like Postman:

# Should return {"message":"Unauthenticated."} — means API is working
GET https://api.yourdomain.com/api/v1/auth/me

# Test login endpoint
POST https://api.yourdomain.com/api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@youragency.com",
  "password": "YourStrongPassword!"
}

Checklist before going live

Check Laravel error logs

# Via SSH
tail -f ~/public_html/api/storage/logs/laravel.log

# Via File Manager
# Navigate to: public_html/api/storage/logs/laravel.log → right-click → View