Version 2.0 — Laravel 13

Complete Installation & User Guide

Everything you need to deploy, configure, and troubleshoot Lead Nova CRM — the all-in-one sales relationship management platform.

Introduction & Stack Overview

Lead Nova CRM is a comprehensive, feature-rich Customer Relationship Management platform built with a modern, production-ready technology stack. It provides end-to-end sales management including lead capture, deal pipelines, customer management, marketing automation, AI-driven insights, and real-time analytics.

Technology Stack

☰

Laravel

v13

⚙

Alpine.js

✓

Tailwind CSS

★

PHP

8.3+

■

MySQL / PgSQL

8.0+ / 15+

♦

Spatie RBAC

Architecture Highlights

Backend: Laravel 13 with Eloquent ORM, queue workers, scheduled tasks, and event-driven automation engine.
Frontend: Blade templating with Alpine.js 3 for reactive UI components and Tailwind CSS 4 for utility-first styling.
Database: Multi-driver support (MySQL, PostgreSQL, SQLite) with full migration and seeding pipelines.
Security: Envato purchase code verification middleware, Spatie role-based access control (99 permissions, 5 roles), encrypted credential storage, and CSRF/rate-limit protection on all forms.
Caching: 24-hour verified license caching via Laravel Cache facade to minimize Envato API calls.
Automation: Rule-based triggers, multi-step workflows, scheduled jobs, AI lead scoring, and revenue forecasting.

Server Requirements

PHP

8.3 or higher

Database

MySQL 8.0+ / PgSQL 15+ / SQLite 3.40+

Web Server

Apache 2.4+ / Nginx 1.24+

Node.js

20.x or higher (build only)

Composer

2.7+

Memory

512 MB minimum (1 GB recommended)

Required PHP Extensions

Extension	Required For
BCMath	Mathematical operations
Ctype	Character type checking
cURL	HTTP client (Envato API, webhooks, integrations)
DOM	HTML/XML parsing
Fileinfo	MIME type detection for file uploads
Mbstring	Multibyte string operations
OpenSSL	Encryption & HTTPS connections
PDO + Driver	Database access (mysql / pgsql / sqlite)
Tokenizer	PHP tokenizer
XML	XML parsing
Zip	Archive operations
JSON	JSON handling
GD / Imagick	Image processing

Directory Permissions

After deploying the files, set the following permissions to allow the web server to write to specific directories:

# Recursively set writable permissions
chmod -R 775 storage bootstrap/cache

# Ensure the .env file is readable (created by the installer)
chmod 664 .env

# Correct ownership (common web server user)
chown -R www-data:www-data storage bootstrap/cache .env

Important: The web installer will validate these permissions before proceeding. If any directory is not writable, the installer will display an error with the specific path. The directories that must be writable are: storage/, storage/logs/, storage/framework/, storage/framework/cache/, storage/framework/sessions/, storage/framework/views/, and bootstrap/cache/.

Installation Guide

Lead Nova CRM includes a built-in web installer that automates the setup process. Follow the steps below to get your instance running in minutes.

Quick Start: Upload all files to your web server, navigate to https://your-domain.com/install, and follow the on-screen wizard.

Web Installer Wizard

Requirements Check

The installer verifies your PHP version (must be 8.3+), required PHP extensions, and server configuration. Any failing requirement is displayed with a clear error message. Resolve all issues before proceeding to the next step.

Directory Permissions

The installer checks that the following paths are writable by the web server:

storage/ and all subdirectories
bootstrap/cache/
.env (created during this step if missing)

If any path is not writable, the installer shows the exact command needed to fix it. Run the chmod command on your server and refresh the page.

Database Configuration

Enter your database credentials. Supported drivers:

Driver	Default Port	Notes
MySQL / MariaDB	3306	Requires a pre-created database
PostgreSQL	5432	Requires a pre-created database
SQLite	—	File path (auto-created if missing)

The installer tests the connection before proceeding. Once verified, it automatically:

Creates or updates the .env file with your database credentials
Runs all database migrations (creates all tables)
Seeds the database with roles, permissions, and demo data (6 users, 5 roles, 99 permissions, sample leads, deals, customers, tasks, and activity logs)

Admin Account Creation

Create the first Super Admin user to access the CRM. You will need:

Name — Your full name
Email — Used for login and notifications
Password — Minimum 8 characters, confirmed
Phone — Optional contact number

After submission, the installer sets APP_INSTALLED=true in your .env file, clears all caches, and redirects you to the completion page.

Manual Installation (Alternative)

If you prefer command-line setup or the web installer is not accessible, follow these steps:

1. Install Dependencies

composer install --no-dev --optimize-autoloader
npm install
npm run build

2. Configure Environment

cp .env.example .env
php artisan key:generate

Edit .env with your database credentials and application URL:

APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=lead_nova_crm
DB_USERNAME=root
DB_PASSWORD=your_password

ENVATO_PERSONAL_TOKEN=your_token

3. Run Migrations & Seeders

php artisan migrate --seed
php artisan storage:link

4. Set Permissions

chmod -R 775 storage bootstrap/cache
chmod 664 .env

5. Set Installed Flag

echo 'APP_INSTALLED=true' >> .env
php artisan config:clear

Security Notice: After installation, the /install routes are automatically disabled when APP_INSTALLED=true is set in the .env file. For additional security, remove or password-protect the install routes in production.

Cron Job & Queue Worker Configuration

Lead Nova CRM relies on scheduled tasks and queue workers for background operations such as email importing, automation rule execution, notification dispatch, and data maintenance. Both must be configured for the CRM to function fully.

Cron Job (Scheduler)

The Laravel scheduler runs scheduled tasks every minute. Add the following entry to your server's crontab:

* * * * * cd /path/to/lead-nova-crm && php artisan schedule:run >> /dev/null 2>&1

Tip: The >> /dev/null 2>&1 prevents cron from sending an email every minute. If you want to log scheduler output for debugging, replace /dev/null with a log file path: >> storage/logs/scheduler.log 2>&1.

To edit your crontab, run:

crontab -e

Verify the scheduler is working by running it manually:

php artisan schedule:run

Predefined Scheduled Tasks

Task	Frequency	Description
Email Lead Import	Every 5 minutes	Fetches unseen emails from configured IMAP inbox and creates leads
Cache Pruning	Hourly	Cleans up expired cache entries from the database cache store
Automation Engine	Every minute	Evaluates and triggers automation rules and workflows

Queue Worker

The queue worker processes queued jobs (e.g., email sending, webhook dispatch, notification delivery). The CRM uses the database queue driver by default.

Start the queue worker:

php artisan queue:work --sleep=3 --tries=3 --max-time=3600

Note: The --sleep=3 flag tells the worker to sleep for 3 seconds when no job is available. The --tries=3 flag limits retries per job. The --max-time=3600 flag restarts the worker after 1 hour to prevent memory leaks.

Production Setup with Supervisor

For production environments, use Supervisor to keep the queue worker running persistently. Create a configuration file at /etc/supervisor/conf.d/leadnova-queue.conf:

[program:leadnova-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/lead-nova-crm/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/path/to/lead-nova-crm/storage/logs/queue-worker.log

After creating the file, reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start leadnova-queue:*

Monitor queue worker status:

sudo supervisorctl status
php artisan queue:status

Envato License Activation & Troubleshooting

Lead Nova CRM includes a mandatory license verification system that validates your purchase code against the Envato Market API before granting access to the application.

How License Verification Works

Registration: When a user logs in for the first time, the VerifyLicense middleware intercepts all authenticated routes.
Redirection: If no valid purchase code is stored in the database, the user is redirected to /license.
API Validation: The user enters their 36-character purchase code. The application sends a request to the Envato Market API v3 endpoint (https://api.envato.com/v3/market/author/sale?code=PURCHASE_CODE) with the configured Personal Token.
Encrypted Storage: On successful validation, the purchase code is encrypted using Laravel's Crypt::encryptString() and stored in the settings table.
Caching: The verification result is cached for 24 hours (configurable via ENVATO_CACHE_DURATION) to avoid hitting Envato API rate limits on every page load.

Configuration

Add the following to your .env file:

ENVATO_PERSONAL_TOKEN=your_token_here
ENVATO_CACHE_DURATION=86400

Generating a Personal Token

Log in to your Envato account
Navigate to https://build.envato.com/create-token/
Enter a token name (e.g., "Lead Nova CRM License Verification")
Select the "Verify Purchases" permission scope
Click "Create Token" and copy the generated token
Add it to your .env file as ENVATO_PERSONAL_TOKEN

Troubleshooting Common Issues

● Redirect Loop After Login

Symptom: Browser shows ERR_TOO_MANY_REDIRECTS after logging in.

Cause: The /license route was previously protected by the guest middleware, which redirected authenticated users away from the license page, creating a redirect loop between /dashboard and /license.

Fix: Ensure routes/license.php does not use the guest middleware. The license routes should be publicly accessible. The VerifyLicense middleware already excludes /license* from the license check, so there is no security risk. Clear your browser cookies and cache after making this change.

● "Envato Personal Token is not configured"

Symptom: The license verification form returns an error saying the personal token is missing.

Cause: The ENVATO_PERSONAL_TOKEN environment variable is empty or not set.

Fix: Add your Envato Personal Token to the .env file and run php artisan config:clear to reload configuration.

● "The purchase code is invalid or does not exist"

Symptom: A valid purchase code is rejected.

Checklist:

Verify the purchase code is exactly 36 characters in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Ensure the Personal Token was generated from the same Envato account that owns the item
Confirm the token has the "Verify Purchases" permission scope
Check that your server can make outbound HTTPS requests to api.envato.com (not blocked by a firewall)

● "Unable to verify purchase code. Please try again later."

Symptom: The Envato API returns a non-200/non-404 status code.

Cause: The Envato API might be temporarily unavailable, or your server is rate-limited.

Fix: Wait a few minutes and try again. The verification is cached for 24 hours, so once successful, repeated checks will not hit the API. Check your storage/logs/laravel.log for detailed error messages from EnvatoVerificationService.

● "Connection to verification server failed"

Symptom: A network-level error occurs when contacting the Envato API.

Cause: The cURL request timed out or the server cannot reach api.envato.com.

Fix: Verify your server's DNS resolution and outbound internet connectivity. Test with: curl -I https://api.envato.com/v3/market/author/sale. If behind a proxy, ensure PHP cURL is configured to use it.

● License Verification Cached Stale Result

Symptom: License status does not update after correcting the purchase code.

Fix: Clear the application cache:

php artisan optimize:clear

This clears the envato_license_status and envato_verify_* cache keys, forcing a fresh verification on the next request.