Deployment Guide — Song Lyrics Generator

1 Prerequisites & Requirements

Before deploying, ensure the following are available:

Namecheap Stella Plan — supports PHP 8.2+, MySQL, SSH access, and cron jobs.
Domain linked to your Namecheap hosting account.
SSH Access — enable via cPanel → "SSH Access" → "Manage SSH Keys".
Node.js & NPM installed locally (for building Vite assets before upload).
Composer installed locally.
FTP Client (FileZilla) or use cPanel File Manager.
Groq API Key for the AI lyrics generation feature.

⚠️

Namecheap shared hosting does NOT support running npm or node on the server. You must build all Vite/Tailwind assets locally before uploading.

2 Local Preparation (Build Assets)

Run these commands in your project root on your local machine:

2.1 Install PHP Dependencies (production only)

composer install --optimize-autoloader --no-dev

2.2 Install Node Dependencies & Build

npm install
npm run build

This generates compiled assets in the public/build/ directory.

2.3 Verify Build Output

Ensure public/build/manifest.json exists and public/build/assets/ contains your compiled CSS & JS files.

3 cPanel: Create MySQL Database

Log in to cPanel from your Namecheap dashboard.
Go to MySQL® Databases.
Create a new database: youraccount_songlyrics
Create a new user: youraccount_slguser with a strong password.
Add user to the database with ALL PRIVILEGES.

⚠️

Namecheap prefixes database and user names with your cPanel username (e.g., cpanelusr_songlyrics). Note the full names for your .env file.

4 Configure .env for Production

Create/edit your .env file with production values:

APP_NAME="Song Lyrics Generator"
APP_ENV=production
APP_KEY=base64:YJdq5RoV7iCfxxdWzjZ2LexparFxBB6I1yvu5B1GhiE=
APP_DEBUG=false
APP_URL=https://yourdomain.com

LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=cpanelusr_songlyrics
DB_USERNAME=cpanelusr_slguser
DB_PASSWORD=your_strong_password_here

GROQ_API_KEY=your_groq_api_key_here

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database
FILESYSTEM_DISK=local

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=465
MAIL_USERNAME=noreply@yourdomain.com
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=ssl
MAIL_FROM_ADDRESS="noreply@yourdomain.com"
MAIL_FROM_NAME="Song Lyrics Generator"

🔴

Critical: Set APP_DEBUG=false and APP_ENV=production. Leaving debug mode on exposes sensitive information (API keys, DB credentials) to the public.

⚠️

Generate a new APP_KEY for production: run php artisan key:generate locally, then copy the key to your production .env.

5 Upload Files to Hosting

You have two options: FTP (FileZilla) or cPanel File Manager.

5.1 What to Upload

Upload the entire project except the following:

# DO NOT upload these:
node_modules/
.git/
tests/
.env.example
.phpunit.result.cache
.editorconfig

5.2 Upload Destination

Upload everything to a folder outside the public web root:

/home/youraccount/songlyrics/

Do NOT upload the entire project into public_html.

5.3 Recommended Method — ZIP & Extract

Zip the project folder locally (excluding items from 5.1).
Upload the ZIP via cPanel File Manager to /home/youraccount/.
Extract the ZIP in File Manager (right-click → Extract).
Rename the extracted folder to songlyrics.

6 Directory Structure on Server

After uploading, your server structure should look like this:

/home/youraccount/ ├── songlyrics/ # Laravel project root │ ├── app/ │ ├── bootstrap/ │ ├── config/ │ ├── database/ │ ├── public/ # Contains index.php, .htaccess, build/ │ ├── resources/ │ ├── routes/ │ ├── storage/ │ ├── vendor/ │ ├── .env │ ├── artisan │ └── composer.json │ └── public_html/ # Symlinked or contents from public/ ├── .htaccess ├── index.php # Modified to point to songlyrics/ ├── favicon.ico ├── robots.txt └── build/ # Compiled Vite assets

7 Point Document Root (public folder)

The web server must serve files from Laravel's public/ directory. On shared hosting, you have two approaches:

Option A: Copy public/ contents to public_html (Recommended)

Copy all contents of /home/youraccount/songlyrics/public/ into /home/youraccount/public_html/.
Edit /home/youraccount/public_html/index.php to update the paths:

<?php

use Illuminate\Http\Request;

define('LARAVEL_START', microtime(true));

// Determine if the application is in maintenance mode...
if (file_exists($maintenance = __DIR__.'/../songlyrics/storage/framework/maintenance.php')) {
    require $maintenance;
}

// Register the Composer autoloader...
require __DIR__.'/../songlyrics/vendor/autoload.php';

// Bootstrap Laravel and handle the request...
(require_once __DIR__.'/../songlyrics/bootstrap/app.php')
    ->handleRequest(Request::capture());

Option B: Symlink (if SSH available)

# SSH into server
ssh youraccount@yourserver

# Backup and remove default public_html
mv public_html public_html_backup

# Create symlink
ln -s /home/youraccount/songlyrics/public /home/youraccount/public_html

⚠️

Option A is recommended because some Namecheap shared hosting configurations do not follow symlinks. If Option B doesn't work, fall back to Option A.

8 Set File Permissions

Via SSH or cPanel File Manager, set the correct permissions:

# SSH into your server, then:
cd /home/youraccount/songlyrics

# Storage and cache must be writable
chmod -R 775 storage
chmod -R 775 bootstrap/cache

# Ensure artisan is executable
chmod +x artisan

Or via cPanel File Manager: right-click the storage and bootstrap/cache folders → Change Permissions → set to 775 recursively.

9 Run Migrations & Optimize

Connect via SSH and run these commands:

9.1 Run Database Migrations

cd /home/youraccount/songlyrics

# Set PHP version (Namecheap may have multiple)
# Use the full path to PHP 8.2+
/usr/local/bin/ea-php82 artisan migrate --force

⚠️

If the php command defaults to an older version, find the correct binary with: ls /usr/local/bin/ea-php* and use the 8.2+ version explicitly.

9.2 Create Storage Link

/usr/local/bin/ea-php82 artisan storage:link

9.3 Cache Configuration for Performance

# Cache routes, config, and views
/usr/local/bin/ea-php82 artisan config:cache
/usr/local/bin/ea-php82 artisan route:cache
/usr/local/bin/ea-php82 artisan view:cache

✅

If you ever update the .env file, you MUST run php artisan config:cache again for the changes to take effect.

10 SSL & Domain Setup

10.1 Enable Free SSL

Go to cPanel → SSL/TLS Status.
Click "Run AutoSSL" to provision a free SSL certificate (Sectigo).
Wait a few minutes for it to activate.

10.2 Force HTTPS

Add to the top of public_html/.htaccess:

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

10.3 Update APP_URL

Ensure your .env has the correct URL:

APP_URL=https://yourdomain.com

Then re-cache config: php artisan config:cache

11 Cron Jobs (Laravel Scheduler)

If your app uses the Laravel task scheduler or queued jobs:

Go to cPanel → Cron Jobs.
Add a new cron job with interval Every Minute (* * * * *):

/usr/local/bin/ea-php82 /home/youraccount/songlyrics/artisan schedule:run >> /dev/null 2>&1

Queue Worker (Optional)

Shared hosting doesn't support persistent queue workers. Use the sync driver or configure the scheduler to process jobs:

# In .env, change to sync if queue worker is not needed:
QUEUE_CONNECTION=sync

⚠️

If you need background queue processing on shared hosting, set up a cron to run queue:work --stop-when-empty every minute instead.

12 Post-Deployment Checklist

APP_ENV=production and APP_DEBUG=false are set
New APP_KEY generated for production
GROQ_API_KEY is set with a valid key
Database credentials are correct and migrations ran
storage/ and bootstrap/cache/ are writable (775)
public/build/ contains compiled Vite assets
storage:link has been created
SSL certificate is active and HTTPS is forced
Config, routes, and views are cached
Homepage loads correctly at https://yourdomain.com
User registration and login work
Lyrics generation works (test with a sample request)
Community page loads and displays shared lyrics
History page shows user's generated lyrics
.env file is NOT accessible via browser

13 Troubleshooting

500 Internal Server Error

Check storage/logs/laravel.log for the detailed error.
Verify storage/ and bootstrap/cache/ permissions are 775.
Ensure PHP version is 8.2+: check in cPanel → MultiPHP Manager.
Run php artisan config:clear then php artisan config:cache.

404 on All Routes (except homepage)

Ensure mod_rewrite is enabled (it is by default on Namecheap).
Verify .htaccess exists in public_html/.
Check that AllowOverride All is set (default on Namecheap).

Vite Assets Not Loading (unstyled page)

Confirm public/build/manifest.json exists.
Ensure you ran npm run build locally before uploading.
Check that APP_URL in .env is correct.

Groq API Not Working

Verify GROQ_API_KEY is set in .env.
After changing .env, run php artisan config:cache.
Check if Namecheap blocks outbound HTTPS requests (rare but possible — contact support).
Review storage/logs/laravel.log for API error details.

"Class Not Found" Errors

/usr/local/bin/ea-php82 /home/youraccount/songlyrics/artisan clear-compiled
cd /home/youraccount/songlyrics && /usr/local/bin/ea-php82 $(which composer) dump-autoload --optimize

PHP Version Issues

Go to cPanel → MultiPHP Manager.
Select your domain and set PHP version to 8.2 or higher.
Go to MultiPHP INI Editor and ensure these extensions are enabled: mbstring, openssl, pdo_mysql, tokenizer, xml, ctype, json, bcmath, fileinfo, curl.

Song Lyrics Generator

Table of Contents