Toggle Content goes here

Server Requirements

  • PHP: 8.1 or higher
  • MySQL: 5.7+ or MariaDB: 10.3+
  • Apache: 2.4+ with mod_rewrite enabled OR Nginx: 1.15+
  • Composer: Latest version
  • Node.js: 16+ (for asset compilation)
  • SSL Certificate: Required for production

PHP Extensions

Ensure the following PHP extensions are installed:

  • BCMath
  • Ctype
  • cURL
  • DOM
  • Fileinfo
  • JSON
  • Mbstring
  • OpenSSL
  • PDO
  • PDO_MySQL
  • Tokenizer
  • XML
  • GD or Imagick
  • Redis (optional, for caching)

Recommended Server Specifications

  • RAM: Minimum 2GB, Recommended 4GB+
  • Storage: Minimum 5GB free space
  • CPU: 2+ cores recommended

Installation Guide

Step 1: Download and Extract Files

  1. Download the application files from CodeCanyon
  2. Extract the zip file to your desired directory
  3. Upload files to your web server (typically /public_html or /var/www/html)

Step 2: Set Up Database

Using phpMyAdmin to Set Up the Database

If you prefer a graphical interface, follow these steps to create and configure your database using phpMyAdmin:

  1. Log in to phpMyAdmin:
    • Open your web browser and go to http://localhost/phpmyadmin (or the equivalent URL for your server).
    • Log in using your MySQL credentials.
  2. Create a New Database:
    • Click the Databases tab in the top menu.
    • In the Create database section, enter your desired database name (e.g., your_email_app_db).
    • Choose utf8mb4_unicode_ci as the collation for full Unicode support.
    • Click Create to generate the database.
  3. Create a Database User (Optional but Recommended):
    • Navigate to the User Accounts tab.
    • Click Add user account and enter a username (e.g., email_app_user).
    • Set a strong password.
    • Under Global privileges, grant all privileges or customize them as needed.
    • Click Go to create the user.
  4. Import the SQL File:
    • Click on the newly created database (your_email_app_db) in the left sidebar.
    • Go to the Import tab.
    • Click Choose File and select your .sql file.
    • Click Go to import the database structure and data.
  5. Verify the Database Setup:
    • Click on the database name to view the tables and ensure they were created successfully.
    • You can use the Browse function to check the data inside tables.
SQL
  1. Ensure MySQL is installed: Make sure MySQL is running on your local or remote server.
  2. Create the Database: Run the following command in your MySQL terminal or a database management tool like phpMyAdmin or MySQL Workbench:
    -- Create database
    CREATE DATABASE your_email_app_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  3. Create the Database: Run the following command in your MySQL terminal or a database management tool like phpMyAdmin or MySQL Workbench:
    -- Create database
    CREATE DATABASE your_email_app_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    -- Create database user (optional but recommended)
    CREATE USER 'email_app_user'@'localhost' IDENTIFIED BY 'strong_password_here';
    GRANT ALL PRIVILEGES ON your_email_app_db.* TO 'email_app_user'@'localhost';
    FLUSH PRIVILEGES;
  4. Create the user: Run the following command in your MySQL terminal or a database management tool like phpMyAdmin or MySQL Workbench:
    -- Create database user (optional but recommended)
    CREATE USER 'email_app_user'@'localhost' IDENTIFIED BY 'strong_password_here';
    GRANT ALL PRIVILEGES ON your_email_app_db.* TO 'email_app_user'@'localhost';
    FLUSH PRIVILEGES;
  5. Import the .sql File: Run the following command in your MySQL terminal or a database management tool like phpMyAdmin or MySQL Workbench using the .SQL file that you found in the installation files. Replace path/to/your/database.sql with the actual location of the .sql file. You will be prompted to enter the password for email_app_user.
    mysql -u email_app_user -p your_email_app_db < path/to/your/database.sql;
  • Ensure the Database is Properly Imported
    • Before updating the admin user, confirm that your database has been successfully imported.
    • You can check this by logging into your MySQL database and viewing the users table:
      sql
      SELECT * FROM users;
      

      This will list all users and confirm that the required admin record (id = 1) exists.

  • Run the Update Query to Modify Admin Details
    • If the admin user already exists in your users table, run the following SQL query to update their information:
      sql
      UPDATE users 
      SET name = 'Solomon Bareebe', email = 'solomon@tutajua.com' 
      WHERE id = 1;
      
    • This query updates the user’s name and email address where the id is 1.
    • If the user with id = 1 does not exist, the query will not have any effect.
  • Verify the Changes
    • To ensure the update was successful, retrieve the modified record using:
      sql
      SELECT * FROM users WHERE id = 1;
      
    • This will show the newly updated admin information.
  • Clear Cache (If Using Laravel)
    • If your application is built with Laravel, cached configurations might prevent immediate changes from reflecting. Run:
      sh
      php artisan config:clear
      php artisan cache:clear
      
    • This ensures Laravel fetches the latest database values instead of old cached ones.

Edit the .env file with your settings:

env
APP_NAME="Your Email Marketing App"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Database Configuration
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_email_app_db
DB_USERNAME=email_app_user
DB_PASSWORD=your_database_password

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-server.com
MAIL_PORT=587
MAIL_USERNAME=your-email@yourdomain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

# Queue Configuration (Important for bulk emails)
QUEUE_CONNECTION=database

# Session and Cache
SESSION_DRIVER=database
CACHE_DRIVER=file

# AWS SES (Optional - for better deliverability)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
SES_KEY="${AWS_ACCESS_KEY_ID}"
SES_SECRET="${AWS_SECRET_ACCESS_KEY}"
SES_REGION="${AWS_DEFAULT_REGION}"

RECAPTCHA_SITE_KEY=your_site_key
RECAPTCHA_SECRET_KEY=your_site_secret
RECAPTCHA_SITE_KEY_V3=your_site_key_v3
RECAPTCHA_SECRET_KEY_V3=your_site_secret_v3

Step 3: Install Dependencies

This step is optional because the zip file contains all the PHP dependencies and JavaScript assets.
bash
# Install PHP dependencies
composer install --optimize-autoloader --no-dev

# Install Node.js dependencies and build assets
npm install
npm run production

# Generate application key
php artisan key:generate

# Create storage symlink
php artisan storage:link

Step 4: Set File Permissions

bash
# Set correct permissions for Laravel
sudo chown -R www-data:www-data /path/to/your/app
sudo chmod -R 755 /path/to/your/app
sudo chmod -R 775 /path/to/your/app/storage
sudo chmod -R 775 /path/to/your/app/bootstrap/cache

Step 5: Configure Web Server

Htaccess Configuration

Create or update .htaccess in your project root:

apache

    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]

Nginx Configuration

nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/your/app/public;
    
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    
    index index.php;
    
    charset utf-8;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
    
    error_page 404 /index.php;
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache Configuration

Apache
<virtualhost< span=""> *:80>
    ServerName yourdomain.com;
    Redirect permanent / https://yourdomain.com/;
</virtualhost<>>

<virtualhost< span=""> *:443>
    ServerName yourdomain.com;
    DocumentRoot /path/to/your/app/public;

    SSLEngine on;
    SSLCertificateFile /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    SSLCertificateChainFile /etc/letsencrypt/live/yourdomain.com/chain.pem;

    <directory< span=""> /path/to/your/app/public>
        AllowOverride All;
        Require all granted;
    </directory<>>

    <filesmatch< span=""> "\.php$">
        SetHandler "proxy:unix:/var/run/php/php8.1-fpm.sock|fcgi://localhost/";
    </filesmatch<>>

    ErrorDocument 404 /index.php;

    CustomLog ${APACHE_LOG_DIR}/access.log combined;
    ErrorLog ${APACHE_LOG_DIR}/error.log;
</virtualhost<>>

Email Service Providers

SMTP Configuration

env
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls

AWS SES Configuration

env
MAIL_MAILER=ses
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
MAIL_FROM_ADDRESS=verified@yourdomain.com

Mailgun Configuration

env
MAIL_MAILER=mailgun
MAILGUN_DOMAIN=your-domain.com
MAILGUN_SECRET=your-mailgun-secret
MAILGUN_ENDPOINT=api.mailgun.net

Queue Configuration

For handling bulk email sending, configure queues:

bash
# Set queue driver in .env
QUEUE_CONNECTION=database

# Create queue jobs table
php artisan queue:table
php artisan migrate

# Run queue worker (use process manager like Supervisor)
php artisan queue:work --sleep=3 --tries=3 --max-time=3600

Supervisor Configuration (Recommended)

Supervisor is required to manage queue workers efficiently. Follow these steps to install and configure it:

  1. Install Supervisor:
    sh
    sudo apt update
    sudo apt install supervisor
    
  2. Enable and Start Supervisor:
    sh
    sudo systemctl enable supervisor
    sudo systemctl start supervisor
    
  3. Verify Installation:
    sh
    sudo systemctl status supervisor
    
  4. Create Supervisor Configuration for Laravel Queue Worker: Create a new configuration file:

    Create /etc/supervisor/conf.d/email-app-worker.conf:

    sh

    sudo nano /etc/supervisor/conf.d/email-app-worker.conf
    

    Add the following content:

    ini
    [program:email-app-worker]
    process_name=%(program_name)s_%(process_num)02d
    command=php /path/to/your/app/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/your/app/storage/logs/worker.log
    stopwaitsecs=3600
    
  5. Reload Supervisor and Start the Worker:
    sh
    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl start email-app-worker
    
  6. Check Supervisor Logs:
    sh
    sudo journalctl -u supervisor --no-pager | tail -20
    

Generating a Laravel Application Key

Laravel requires a unique application key for security. Follow these steps to generate one:

  1. Ensure You Are in Your Laravel Project Directory:
    sh
    cd /path/to/your/app
    
  2. Generate the Application Key:
    sh
    php artisan key:generate
    
  3. Confirm the Key Has Been Updated in the .env File:
    sh
    cat .env | grep APP_KEY
    
  4. Clear the Cache to Apply Changes:
    sh
    php artisan config:clear