# 🚀 Deployment Guide - CBT Application

## 📋 Prerequisites

### Server Requirements (cPanel)
- PHP 8.2 or higher
- Composer
- Node.js & NPM
- PostgreSQL/MySQL Database
- Git support in cPanel

### Local Requirements
- Git
- GitHub CLI (optional, for creating PRs)
- SSH access to server (optional)

---

## 🌿 Branch Strategy

### Branch Overview

| Branch | Environment | Env File | Usage |
|--------|-------------|----------|-------|
| `main` | Development/Staging | `.env.dev` | Testing environment |
| `master` | Production | `.env.prod` | Live production environment |

### Workflow

```
Feature Branch → Pull Request → main (Dev)
                  ↓
              Testing & QA
                  ↓
              Pull Request → master (Prod)
                  ↓
              Production Deployment
```

---

## 🔧 Initial Server Setup

### 1. Setup Git Repository in cPanel

1. Login to cPanel
2. Go to **Git™ Version Control**
3. Click **Create**
4. Configure:
   - **Clone URL**: `https://github.com/YOUR_USERNAME/cbtQ.git`
   - **Repository Path**: `cbtQ`
   - **Branch**: `master` (or `main`)
5. Click **Create**

> **📝 Note**: The `.cpanel.yml` file in your repository defines automatic deployment actions that will run when cPanel pulls from Git. No manual configuration needed!

### How `.cpanel.yml` Works

The `.cpanel.yml` file automates deployment when cPanel pulls changes:

**For `master` branch (Production):**
- Copies `.env.prod` → `.env`
- Runs `composer install --no-dev`
- Builds assets with `npm run build`
- Clears and caches Laravel configs
- Runs database migrations
- Sets proper permissions

**For `main` branch (Development):**
- Copies `.env.dev` → `.env`
- Same deployment steps as master

### 2. Setup Document Root

1. Go to **Subdomains** or **Addon Domains**
2. Point your domain to: `/home/USER/public_html/cbtQ/public`

### 3. Setup Cron Jobs (Optional)

For queue workers and scheduled tasks:

```bash
# cPanel → Cron Jobs
* * * * * /usr/local/bin/php /home/USER/public_html/cbtQ/artisan schedule:run >> /dev/null 2>&1
```

---

## 🤖 Automated Deployment with cPanel Git

### Using cPanel Git Interface (Easiest)

Once you've set up the Git repository in cPanel:

#### Deploy to Production (master)
1. Go to **cPanel → Git™ Version Control**
2. Find your repository
3. Click **Update** or **Pull**
4. cPanel will automatically run `.cpanel.yml` actions for `master` branch
5. Done! ✅

#### Deploy to Development (main)
1. Switch repository branch to `main` in cPanel
2. Click **Update** or **Pull**
3. cPanel will automatically run `.cpanel.yml` actions for `main` branch
4. Done! ✅

### What Happens During Automated Deployment?

When you click **Pull** in cPanel, the `.cpanel.yml` file triggers:

```bash
# For master branch:
cp .env.prod .env
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan cache:clear && php artisan config:clear
php artisan migrate --force
chmod -R 755 storage bootstrap/cache

# For main branch:
cp .env.dev .env
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan cache:clear && php artisan config:clear
php artisan migrate --force
chmod -R 755 storage bootstrap/cache
```

### Manual Pull via SSH (Alternative)

If you prefer SSH access:

```bash
# SSH into server
ssh user@yourdomain.com

# Navigate to repository
cd ~/public_html/cbtQ

# Pull latest changes
git pull origin master  # or main

# Deployment is automatic via .cpanel.yml!
```

---

## 📦 Manual Deployment Process

### Option 1: Using Deployment Script (Recommended)

```bash
# Make script executable
chmod +x deploy.sh

# Deploy to production (master branch)
git checkout master
./deploy.sh

# Deploy to development (main branch)
git checkout main
./deploy.sh
```

### Option 2: Manual Steps

```bash
# 1. Switch to target branch
git checkout master  # or main

# 2. Pull latest changes
git pull origin master

# 3. Copy environment file
cp .env.prod .env  # or .env.dev for main branch

# 4. Install dependencies
composer install --no-dev --optimize-autoloader
npm ci
npm run build

# 5. Clear and cache configs
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 6. Run migrations
php artisan migrate --force

# 7. Set permissions
chmod -R 755 storage bootstrap/cache
```

---

## 🔄 Pull Request Workflow

### Using GitHub CLI (Recommended)

```bash
# Make script executable
chmod +x create-pr.sh

# Create PR to main (development)
./create-pr.sh
# Choose option 1 for main

# Create PR to master (production)
./create-pr.sh
# Choose option 2 for master
```

### Manual PR Creation

```bash
# 1. Commit your changes
git add .
git commit -m "Your commit message"
git push origin feature-branch

# 2. Create PR via GitHub web interface
# https://github.com/YOUR_USERNAME/cbtQ/compare/main...feature-branch
```

### PR Template

```markdown
### Changes
Describe your changes here

### Environment
- Target Branch: main/master
- Environment File: .env.dev/.env.prod

### Testing
- [ ] Tested locally
- [ ] Tested on staging
- [ ] Database migrations included
- [ ] Asset rebuild needed

### Deployment Notes
Any special instructions for deployment
```

---

## 🔐 Environment Files

### `.env.dev` (Development - main branch)

```env
APP_NAME=Cbtapps
APP_ENV=development
APP_DEBUG=true
APP_URL=https://dev.yourdomain.com
APP_DOMAIN=dev.yourdomain.com

DB_CONNECTION=pgsql
DB_HOST=dev-db-host.com
DB_DATABASE=cbtapps_dev
DB_USERNAME=dev_user
DB_PASSWORD=dev_password

# Other dev-specific configs...
```

### `.env.prod` (Production - master branch)

```env
APP_NAME=Cbtapps
APP_ENV=production
APP_DEBUG=false  # IMPORTANT: Must be false in production!
APP_URL=https://yourdomain.com
APP_DOMAIN=yourdomain.com

DB_CONNECTION=pgsql
DB_HOST=prod-db-host.com
DB_DATABASE=cbtapps_prod
DB_USERNAME=prod_user
DB_PASSWORD=prod_secure_password

# Production-specific configs...
```

---

## 🛡️ Security Checklist

### Before Production Deployment

- [ ] `APP_DEBUG=false` in `.env.prod`
- [ ] Strong database password
- [ ] Secure `APP_KEY` (use `php artisan key:generate`)
- [ ] HTTPS enabled
- [ ] File uploads restricted
- [ ] CORS configured properly
- [ ] Queue workers running (if using queues)
- [ ] Backup strategy in place

### File Permissions

```bash
# Storage and cache directories
chmod -R 755 storage bootstrap/cache

# Make files read-only
chmod 644 storage/logs/*.log
chmod 600 .env

# Prevent direct access to sensitive files
# (Already handled by .htaccess)
```

---

## 🔍 Troubleshooting

### Common Issues

#### 1. 500 Internal Server Error

```bash
# Check Laravel logs
tail -f storage/logs/laravel.log

# Check permissions
ls -la storage bootstrap/cache

# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan view:clear
composer dump-autoload
```

#### 2. Database Connection Failed

```bash
# Verify database credentials
cat .env | grep DB_

# Test connection
php artisan tinker
>>> DB::connection()->getPdo();

# Check if database server is accessible
telnet db-host.com 5432
```

#### 3. Assets Not Loading

```bash
# Rebuild assets
npm run build

# Clear view cache
php artisan view:clear

# Check storage link
php artisan storage:link
```

#### 4. Git Deployment Not Working

- Verify cPanel Git repository is properly cloned
- Check branch name matches (main/master)
- Ensure `.htaccess` exists in `public/` directory
- Review cPanel error logs

---

## 📊 Monitoring

### Health Check

```bash
# Check application status
curl https://yourdomain.com/api/health

# Check queue status
php artisan queue:failed

# Check schedule:run logs
tail -f /home/USER/cron_output.log
```

### Log Files

```bash
# Laravel logs
tail -f storage/logs/laravel.log

# PHP error logs (cPanel)
tail -f /home/USER/public_html/error_log

# Web server error logs
tail -f /var/log/apache2/error_log
```

---

## 🔄 Rollback Procedure

If deployment fails:

```bash
# 1. Revert to previous commit
git checkout HEAD~1

# 2. Or switch to stable branch
git checkout master
git pull origin master

# 3. Restore database (if needed)
php artisan migrate:rollback --step=1

# 4. Clear caches
php artisan cache:clear

# 5. Rebuild assets
npm run build
```

---

## 📞 Support

For issues or questions:
- Check Laravel documentation: https://laravel.com/docs
- cPanel Git guide: https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-deployment/
- Project repository: https://github.com/YOUR_USERNAME/cbtQ

---

## 📝 Quick Reference

### Essential Commands

```bash
# Deploy to production
git checkout master && git pull && cp .env.prod .env && composer install --no-dev && npm ci && npm run build && php artisan migrate --force && php artisan cache:clear

# Deploy to development
git checkout main && git pull && cp .env.dev .env && composer install --no-dev && npm ci && npm run build && php artisan migrate --force && php artisan cache:clear

# Create PR
chmod +x create-pr.sh && ./create-pr.sh
```

### File Locations

- **Application Root**: `/home/USER/public_html/cbtQ/`
- **Public Files**: `/home/USER/public_html/cbtQ/public/`
- **Environment**: `/home/USER/public_html/cbtQ/.env`
- **Logs**: `/home/USER/public_html/cbtQ/storage/logs/`
- **Uploads**: `/home/USER/public_html/cbtQ/storage/app/public/`

---

**Last Updated**: 2026-03-30
**Version**: 1.0.0