# Installation FAQs

> IMPORTANT: Always back up your database, `.env` file, and `storage/` directory before making any changes to your MailTrixy installation. Incorrect modifications can result in data loss or a broken application.

## Remove Public From URL

### Apache

To remove `/public` from the URL on Apache, create a `.htaccess` file in the root folder and add the following code:

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

To also force HTTPS redirection, use:

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

For more details, read the article on Stack Overflow: How to Remove Public Index from URL

Note: This method does not work for localhost and subfolders, only for domains and subdomains.

### LiteSpeed

If your server runs LiteSpeed (common on shared hosting with cPanel), the same `.htaccess` rules above will work. LiteSpeed is fully compatible with Apache rewrite rules. If you encounter issues, ensure the Rewrite module is enabled in your LiteSpeed configuration, or contact your hosting provider for assistance.

## Hide or Deny Access to .env

The `.env` file contains sensitive information such as database credentials, API keys, and mail settings. To prevent direct access to this file, add the following to a `.htaccess` file in the root folder:

    # Disable Directory listing
    Options -Indexes
    # Block access to .env file

        Order allow,deny
        Deny from all

For Nginx, add the following to your server block:

    location ~ /\.env {
        deny all;
        return 404;
    }

## Debug Mode

Debug mode is helpful for tracking errors during development and troubleshooting, but it should never be left enabled on a live/production site as it exposes sensitive information including database credentials, API keys, and file paths.

To enable debug mode, open your `.env` file and change:

    APP_DEBUG=false    # Change this to true
    APP_DEBUG=true

After resolving the issue, always set it back to `false`:

    APP_DEBUG=false

## 419 Error

A 419 Page Expired error occurs when the CSRF token has expired or is missing. This is a Laravel security feature. Common causes and solutions:

- Session expired - Refresh the page to get a new CSRF token. You can increase the session lifetime in your `.env` file: `SESSION_LIFETIME=240`
- APP_URL mismatch - Ensure `APP_URL` in `.env` matches the actual domain you are accessing (including `https://`)
- SESSION_DOMAIN - Verify `SESSION_DOMAIN` is set correctly in `.env`
- Permissions - Ensure `storage/framework/sessions` directory is writable: `chmod -R 775 storage/framework/sessions`
- Cookies blocked - Check that your browser is not blocking cookies from your domain

## No Application Encryption Key

If you see the error "No application encryption key has been specified", it means the `APP_KEY` value in your `.env` file is missing or empty.

To generate a new application key, run:

    php artisan key:generate

This will automatically set the `APP_KEY` value in your `.env` file. The key should begin with `base64:`. After generating, clear the config cache:

    php artisan config:cache

## .env File Missing

If your `.env` file is missing, MailTrixy will not be able to connect to the database or function properly. To create it:

1. Copy the example environment file:

       cp .env.example .env

2. Generate a new application key:

       php artisan key:generate

3. Open the `.env` file and configure your database credentials, mail settings, and other required values
4. Clear the config cache:

       php artisan config:cache

Note: The `.env` file may be hidden by your file manager. Enable "Show Hidden Files" in cPanel File Manager or use `ls -la` via SSH to see it.

## Internal Server Error & 500

A 500 Internal Server Error indicates a server-side problem. Follow these steps to diagnose and resolve it:

1. Enable debug mode temporarily to see the actual error:

       APP_DEBUG=true

2. Check the Laravel log file for the full stack trace:

       tail -f storage/logs/laravel.log

3. Ensure correct storage permissions:

       chmod -R 775 storage bootstrap/cache
       chown -R www-data:www-data storage bootstrap/cache

4. Verify .env exists with a valid `APP_KEY`
5. Clear all caches:

       php artisan config:clear
       php artisan cache:clear
       php artisan route:clear
       php artisan view:clear

6. Check .htaccess - Ensure the `.htaccess` file in the `public/` directory is present and not corrupted
7. Verify PHP version - MailTrixy requires PHP 8.2 or higher

> Important: Always set `APP_DEBUG=false` in production after debugging. Leaving it enabled exposes sensitive information.

## MySQL Not Creating Table

If you encounter a SQLSTATE error regarding key length when running migrations, such as "Specified key was too long", add the following to your `app/Providers/AppServiceProvider.php` in the `boot()` method:

    use Illuminate\Support\Facades\Schema;

    public function boot()
    {
        Schema::defaultStringLength(191);
    }

This issue commonly occurs with older versions of MySQL (below 5.7.7) or MariaDB (below 10.2.2) that use the `utf8` character set instead of `utf8mb4`. After making the change, re-run the migrations:

    php artisan migrate

## Class 'ZipArchive' Not Found

This error means the PHP `zip` extension is not installed or enabled on your server. MailTrixy uses ZipArchive for update packages and file exports.

To install it:

- Ubuntu/Debian: `sudo apt-get install php-zip && sudo systemctl restart apache2`
- CentOS/RHEL: `sudo yum install php-zip && sudo systemctl restart httpd`
- cPanel: Go to Select PHP Version and enable the `zip` extension

Verify the extension is loaded: `php -m | grep zip`

## curl_init Error

The error "Call to undefined function curl_init()" means the PHP cURL extension is not installed or enabled. MailTrixy requires cURL for connecting to email providers, AI services, payment gateways, and other external APIs.

To install it:

- Ubuntu/Debian: `sudo apt-get install php-curl && sudo systemctl restart apache2`
- CentOS/RHEL: `sudo yum install php-curl && sudo systemctl restart httpd`
- cPanel: Go to Select PHP Version and enable the `curl` extension

Verify the extension is loaded: `php -m | grep curl`

## 404, 403 Errors

### 404 Not Found

If all routes return 404, the issue is typically with your web server configuration:

- Apache: Ensure `mod_rewrite` is enabled and `AllowOverride All` is set in your virtual host:

      sudo a2enmod rewrite
      sudo systemctl restart apache2

- Nginx: Add the `try_files` directive:

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

- Route cache: Regenerate the route cache: `php artisan route:cache`

### 403 Forbidden

A 403 error means the server is denying access. Common causes:

- Incorrect document root - Your web server should point to the `public/` directory, not the project root
- File permissions - Ensure correct ownership and permissions on application files
- Directory indexing disabled - This is normal and expected. Ensure your web server routes requests through `index.php`

## Payload Too Large

A 413 Payload Too Large error occurs when you try to upload a file or send data that exceeds your server's configured limits. To fix this, update the following settings:

### PHP Settings (php.ini)

    upload_max_filesize = 64M
    post_max_size = 64M
    memory_limit = 256M

### Nginx (if applicable)

    client_max_body_size 64M;

Add this inside the `server` or `http` block in your Nginx configuration, then restart Nginx:

    sudo systemctl restart nginx

### Apache (if applicable)

If using Apache with `mod_fcgid`, you may also need:

    FcgidMaxRequestLen 67108864

## exec() Function Disabled

Some features in MailTrixy may require the `exec()` PHP function (e.g., running Artisan commands programmatically). If you see an error about `exec()` being disabled:

- Open your `php.ini` file and find the `disable_functions` directive
- Remove `exec` from the comma-separated list
- Restart your web server

On shared hosting with cPanel, go to Select PHP Version → Options and check if `exec` is in the disabled functions list. If your host does not allow enabling it, contact their support team.

## Storage Link / Images Not Showing

If images, avatars, or uploaded files are not displaying, the storage symbolic link may be missing or broken. MailTrixy requires a symbolic link from `public/storage` to `storage/app/public`.

To create the link, run:

    php artisan storage:link

If you get an error that the link already exists but images still do not show:

1. Delete the existing link:

       rm public/storage

2. Recreate it:

       php artisan storage:link

On shared hosting without SSH access: You can manually create the symbolic link by adding the following to a temporary PHP file (e.g., `public/symlink.php`) and accessing it in your browser:

    <?php
    symlink('../storage/app/public', './storage');
    echo 'Storage link created successfully!';
    ?>

Important: Delete the `symlink.php` file immediately after use for security.