# Deployment Instructions for cPanel

This guide will help you deploy your Laravel application to a cPanel subdomain.

## Prerequisites

- Access to cPanel with your hosting provider
- PHP 8.2 or higher
- MySQL database access
- Composer installed on server (or via cPanel)
- SSH access (recommended) or File Manager access

## Step 1: Database Setup

1. Log into your cPanel
2. Go to **MySQL Databases**
3. Create a new database (e.g., `username_catalogue`)
4. Create a new MySQL user and password
5. Add the user to the database with **ALL PRIVILEGES**
6. Note down:
   - Database name
   - Database username
   - Database password
   - Database host (usually `localhost`)

## Step 2: Upload Files

### Option A: Via File Manager (Recommended for subdomain)

1. Go to **File Manager** in cPanel
2. Navigate to your subdomain folder (usually `public_html/subdomain_name` or `subdomain_name` folder)
3. Upload the deployment ZIP file
4. Extract the ZIP file in the subdomain folder
5. **Important**: Move all contents from the extracted folder to the subdomain root (if extracted into a subfolder)

### Option B: Via SSH

1. Connect via SSH
2. Navigate to your subdomain directory
3. Upload and extract the ZIP file
4. Move files if needed

## Step 3: Folder Structure Setup

For cPanel, you have two options:

### Option A: Subdomain Root = Laravel Root (Recommended)

If your subdomain root is the Laravel project root:
- Point document root to: `/home/username/subdomain_name/public`

In cPanel:
1. Go to **Subdomains**
2. Edit your subdomain
3. Change Document Root to: `public_html/subdomain_name/public` (adjust path as needed)

### Option B: Document Root = Public Folder (Standard)

If cPanel automatically points to public folder:
- Your structure should be: `/home/username/subdomain_name/`
- Files should be extracted here
- The `public` folder will be the document root

## Step 4: Environment Configuration

1. In File Manager, navigate to your Laravel root folder
2. Create a new file named `.env` (make sure it starts with a dot)
3. Copy the contents from `.env.example`
4. Edit the following values:

```env
APP_NAME="Your Site Name"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-subdomain.yourdomain.com

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

# Generate a new APP_KEY (see Step 5)
APP_KEY=
```

## Step 5: Generate Application Key

### Via SSH (Recommended):
```bash
cd /home/username/subdomain_name
php artisan key:generate
```

### Via cPanel Terminal:
1. Go to **Terminal** in cPanel
2. Navigate to your subdomain folder
3. Run: `php artisan key:generate`

## Step 6: Install Dependencies

The deployment ZIP includes `vendor/` and compiled assets (`public/build/`). You usually **do not** need to run `npm run build` on the server.

After extracting the ZIP, `vendor/` may be incomplete or not writable (common on cPanel). If the site returns **HTTP 500**, or `composer install` fails with **"does not exist and could not be created"**, run:

### Via SSH or cPanel Terminal:
```bash
cd /home/username/subdomain_name

# Fix write access
chmod -R u+rwX vendor storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

# Reinstall vendor if extract left it broken or unreadable
rm -rf vendor
mkdir vendor
chmod 775 vendor
composer install --no-dev --optimize-autoloader
```

Replace `username` and `subdomain_name` with your cPanel paths (e.g. `~/public_html/neim-prints.vehinc.co.za`).

Verify:
```bash
ls -la vendor/autoload.php
```

If Composer is not available, re-upload the `vendor/` folder from the deployment ZIP via File Manager, then run the `chmod` commands above.

**Note**: If Composer is not available, you may need to request it from your hosting provider or use cPanel's Composer interface if available.

## Step 7: Set Permissions

### Via SSH:
```bash
cd /home/username/subdomain_name

# Laravel needs write access to storage, bootstrap/cache, and vendor (for composer)
chmod -R u+rwX vendor storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
chown -R username:username vendor storage bootstrap/cache
```

**Note**: Replace `username` with your actual cPanel username. You may need to adjust the group name based on your hosting provider.

### Via File Manager:
1. Right-click on `storage` folder → Change Permissions → Set to `775`
2. Right-click on `bootstrap/cache` folder → Change Permissions → Set to `775`

## Step 8: Run Migrations

### Via SSH:
```bash
php artisan migrate --force
```

### Via cPanel Terminal:
Use the same command.

## Step 9: Create Storage Link (if using public storage)

```bash
php artisan storage:link
```

## Step 10: Clear and Cache Configuration

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## Step 11: Verify Deployment

1. Visit your subdomain URL in a browser
2. Check if the site loads correctly
3. Test key functionality:
   - Homepage loads
   - Products/categories display
   - Contact form works
   - Admin panel accessible (if applicable)

## Troubleshooting

### Permission Errors
- Ensure `storage` and `bootstrap/cache` folders are writable (775)
- Check file ownership matches your cPanel user

### 500 Error
- Check `.env` file exists and is configured correctly
- Verify `APP_KEY` is set (`php artisan key:generate`)
- Check error logs: `storage/logs/laravel.log`
- Enable `APP_DEBUG=true` temporarily (disable after fixing)
- **Vendor folder broken or not writable** (very common after ZIP extract on cPanel):

```bash
cd /home/username/subdomain_name

chmod -R u+rwX vendor storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
rm -rf vendor
mkdir vendor
chmod 775 vendor
composer install --no-dev --optimize-autoloader
```

Symptoms: blank HTTP 500, or Composer error *"vendor/... does not exist and could not be created"*. Confirm fix with `ls -la vendor/autoload.php`.

### Database Connection Error
- Verify database credentials in `.env`
- Check database host (try `localhost` or `127.0.0.1`)
- Ensure database user has proper permissions
- Verify database exists

### Asset Loading Issues
- Run `php artisan config:clear`
- Run `npm run build` if assets are missing
- Check `public/build` folder exists

### Route Not Found (404)
- Run `php artisan route:clear`
- Run `php artisan route:cache`
- Verify `.htaccess` file exists in `public` folder

## Additional Notes

- Keep `APP_DEBUG=false` in production
- Regularly backup your database
- Monitor `storage/logs/laravel.log` for errors
- For better performance, use Redis/Memcached for caching (if available)
- Consider using CloudFlare or similar CDN for static assets

## Support

If you encounter issues:
1. Check Laravel logs: `storage/logs/laravel.log`
2. Check cPanel error logs
3. Verify all steps were completed correctly
4. Contact your hosting provider for server-specific issues