Installation

Before You Start

Make sure your server and local environment meet the minimum requirements below. If you're missing any prerequisites, install them before proceeding.

System Requirements

Laravel Mail Platform requires the following to run:

Requirement	Minimum Version	Notes
PHP	8.3+	Modern version with required extensions (see below)
Git	Any recent version	For cloning the repository
Composer	2.0+	PHP dependency manager (install here)
Database	See below	Choose one database system

Supported Databases

Choose one of the following database systems:

MySQL — Version 5.7 or higher (8.0+ recommended)
PostgreSQL — Version 9.4 or higher (12+ recommended)
SQLite — Version 3.33 or higher (3.39+ recommended)

Database choice tips:

MySQL: Most common choice; widely supported by hosting providers
PostgreSQL: More robust for large datasets; better JSON support
SQLite: Good for development/testing; not recommended for production with multiple concurrent users

PHP Extensions

Laravel Mail Platform requires the following PHP extensions (most come standard):

curl
json
openssl
pdo
mbstring
tokenizer
xml
fileinfo

Run php -m to see which extensions are currently installed.

Checking Your Setup

Verify Prerequisites

Before proceeding, verify each requirement is installed:

# Check PHP version
php --version

# Check Composer is installed
composer --version

# Check Git is installed
git --version

# Check database client (MySQL example)
mysql --version

If any command fails, install the missing software first.

Verify PHP Extensions

Check if required extensions are available:

php -m | grep -E 'curl|json|openssl|pdo|mbstring|tokenizer|xml|fileinfo'

Missing extensions? This depends on your environment:

Ubuntu/Debian:

sudo apt-get install php8.3-curl php8.3-json php8.3-openssl php8.3-pdo php8.3-mbstring php8.3-tokenizer php8.3-xml php8.3-fileinfo

macOS (Homebrew):

brew install php@8.3

Windows: Enable extensions in your php.ini file by uncommenting extension lines, or use a pre-configured PHP distribution like XAMPP.

Installation Steps

Step 1: Clone the Repository

Clone Laravel Mail Platform from the repository:

git clone https://github.com/your-repo/laravel-mail-platform.git
cd laravel-mail-platform

Replace the URL with your actual repository URL.

Step 2: Install Dependencies

Navigate to the project root and install all PHP dependencies using Composer:

composer install

Composer will download and install Laravel Mail Platform and all required packages. This may take a few minutes depending on your connection speed.

Tip: If you encounter permission errors, you may need to run with sudo (Linux/macOS) or use an administrator terminal (Windows).

Step 3: Configure Your Environment

After dependencies are installed, proceed to the Configuration & Setup Guide to:

Create your .env file
Generate an encryption key
Configure your database connection
Set up queue workers
Configure cron jobs
Set up email services

Important: Do not start the server until you've completed the configuration steps. The application will not work without proper .env settings and database migrations.

Web Server Setup

Laravel Mail Platform requires a web server to serve the application. The web server must be configured to point to the public directory of your installation.

Why the `public` Directory?

The public directory contains only the files that should be directly accessible from the web (CSS, JavaScript, images). All sensitive application code remains outside the web root, improving security.

Popular Web Server Configurations

Nginx

Create a new server block in your nginx configuration:

server {
    listen 80;
    server_name campaigns.example.com;

    root /var/www/campaigns.example.com/public;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Save this to /etc/nginx/sites-available/campaigns.conf, enable it, and reload:

sudo ln -s /etc/nginx/sites-available/campaigns.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Apache

Enable the mod_rewrite module and create a virtual host:

sudo a2enmod rewrite

Create a virtual host configuration (e.g., /etc/apache2/sites-available/campaigns.conf):

<VirtualHost *:80>
    ServerName campaigns.example.com
    DocumentRoot /var/www/campaigns.example.com/public

    <Directory /var/www/campaigns.example.com/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/campaigns-error.log
    CustomLog ${APACHE_LOG_DIR}/campaigns-access.log combined
</VirtualHost>

Enable the site and reload:

sudo a2ensite campaigns.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

Local Development (Laravel Artisan Server)

For local development only, you can use Laravel's built-in server:

php artisan serve

This starts a development server at http://127.0.0.1:8000. Do not use this in production.

Verify Your Web Server Setup

After configuring your web server, verify it's working:

Create a test file in /var/www/campaigns.example.com/public/test.txt with some content
Navigate to https://campaigns.example.com/test.txt in your browser
If you see the file content, your web server is configured correctly
Delete the test file when done

Installation Verification

Run the Setup Command (Optional)

Laravel Mail Platform includes an interactive setup command that automates configuration:

php artisan setup

This command will:

Verify system requirements
Create your .env file
Generate an encryption key
Configure database settings
Run migrations
Create an admin user
Set up basic email services

Note: You can also configure everything manually following the Configuration Guide.

Test Your Installation

After setup, verify everything is working:

Navigate to your domain in a browser
Log in with your configured credentials
Try accessing the Campaigns page
Verify no errors appear in storage/logs/laravel.log

Common Installation Issues

"Composer command not found"

Composer is not installed or not in your system PATH. Install Composer and verify with composer --version.

"PHP version does not satisfy requirement"

You have an older version of PHP installed. Install PHP 8.3+:

Ubuntu: sudo apt-get install php8.3-cli
macOS: brew install php@8.3
Windows: Download from php.net

"permission denied" or "cannot write to directory"

The web server user doesn't have permission to write to required directories. Fix this:

sudo chown -R www-data:www-data /var/www/campaigns.example.com
sudo chmod -R 755 /var/www/campaigns.example.com
sudo chmod -R 775 /var/www/campaigns.example.com/storage
sudo chmod -R 775 /var/www/campaigns.example.com/bootstrap/cache

Replace www-data with your web server user (could be www, apache, nginx, etc.).

"SQLSTATE[HY000]: General error: 1030 Got error"

Usually a database connection problem. Verify:

Database server is running: sudo systemctl status mysql (or postgres, etc.)
Connection credentials are correct in .env
Database user has permission to access the specified database

"504 Bad Gateway" or "502 Bad Gateway"

Your PHP application or queue workers are not running. Verify:

PHP-FPM is running: sudo systemctl status php8.3-fpm
Queue workers are running: php artisan queue:work --queue=message-dispatch
Check logs in storage/logs/laravel.log

"Class not found" or "Cannot find database"

Migrations haven't been run or failed. Run:

php artisan migrate:fresh --seed

Next Steps

✅ Installation complete? Proceed to Configuration & Setup to finish configuring your environment.

Installing on a specific platform?

Need help?

Check the Troubleshooting Guide
Review Laravel Deployment Documentation for detailed server setup
Contact support if you're stuck

Production Deployment Considerations

Before deploying to production, also consider:

SSL/TLS certificates — Use HTTPS (Let's Encrypt is free)
Backups — Set up automated database backups
Monitoring — Monitor server resources and logs
Security — Keep PHP, web server, and database updated
Performance — Use Redis for queues, enable caching
Email services — Configure with production credentials
Logging — Monitor storage/logs/ for errors

See the Configuration Guide for detailed security and performance recommendations.