================================================================================
                          Operations & Maintenance Guide
================================================================================

This guide covers day-to-day operations, maintenance tasks, and system
management for your Laravel application on CloudPanel.

================================================================================
                          Laravel Scheduler (Cron Jobs)
================================================================================

Laravel's task scheduler allows you to run automated tasks. Many Laravel
features depend on it (cleanup, notifications, reports, etc.).

Setting Up the Scheduler:

1. In CloudPanel, go to Cron Jobs section
2. Add a new cron job with this command:
   
   * * * * * php /path/to/your/site/artisan schedule:run >> /dev/null 2>&1

3. Replace /path/to/your/site with your actual site path
   Example: /home/myuser/htdocs/rosiya.life

4. Set schedule to run every minute (required)
   Minute: *
   Hour: *
   Day: *
   Month: *
   Weekday: *

5. Save the cron job

Verify it's working:
- Check storage/logs/laravel.log for scheduler activity
- Or create a test scheduled task

Alternative (via SSH):
crontab -e
# Add this line:
* * * * * php /path/to/your/site/artisan schedule:run >> /dev/null 2>&1

================================================================================
                          Queue Workers
================================================================================

Queue workers process background jobs (emails, notifications, heavy tasks).

Check if your app uses queues:
- Look for queued jobs in app/Jobs/
- Check if QUEUE_CONNECTION is set to 'database' or 'redis' in .env

Setting Up Queue Workers:

Option 1: Using Supervisor (Recommended)

1. Install Supervisor (via SSH):
   sudo apt-get install supervisor

2. Create supervisor config:
   sudo nano /etc/supervisor/conf.d/laravel-worker.conf

3. Add this configuration:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your/site/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/site/storage/logs/worker.log
stopwaitsecs=3600

4. Start the workers:
   sudo supervisorctl reread
   sudo supervisorctl update
   sudo supervisorctl start laravel-worker:*

Managing Workers:
# View status
sudo supervisorctl status

# Start workers
sudo supervisorctl start laravel-worker:*

# Stop workers
sudo supervisorctl stop laravel-worker:*

# Restart workers (after code deployment)
sudo supervisorctl restart laravel-worker:*

Option 2: Simple Background Process (Development)

# Run in background
nohup php artisan queue:work --daemon &

# View running queue workers
ps aux | grep queue:work

# Kill queue worker
kill [PID]

Option 3: CloudPanel Cron Job (Limited)

Add cron job to run every minute:
* * * * * php /path/to/your/site/artisan queue:work --stop-when-empty

Note: This is less efficient than Supervisor

================================================================================
                          Application Updates & Deployment
================================================================================

Deployment Checklist:

1. Backup Before Update:
   - Backup database
   - Backup files (especially .env and uploads)

2. Enable Maintenance Mode:
   php artisan down --message="Upgrading..." --retry=60

3. Update Code:
   - Upload new files via CloudPanel File Manager
   - Or pull from Git if using version control

4. Update Dependencies (if composer.json changed):
   composer install --no-dev --optimize-autoloader

5. Run Migrations:
   php artisan migrate --force

6. Clear & Rebuild Caches:
   php artisan optimize:clear
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache

7. Restart Queue Workers (if using):
   sudo supervisorctl restart laravel-worker:*

8. Disable Maintenance Mode:
   php artisan up

9. Verify:
   - Check application loads correctly
   - Test critical functionality
   - Review logs for errors

================================================================================
                          Backup Procedures
================================================================================

Database Backup:

Via CloudPanel:
1. Go to Databases > Your Database
2. Click "Backup"
3. Download the SQL dump

Via SSH (Command Line):
mysqldump -u [username] -p[password] [database] > backup-$(date +%Y%m%d).sql

Automated Daily Backup Script:
#!/bin/bash
DATE=$(date +%Y%m%d)
mysqldump -u dbuser -pdbpass dbname > /backups/db-$DATE.sql
# Keep only last 7 days
find /backups -name "db-*.sql" -mtime +7 -delete

File Backup:

Important directories to backup:
- storage/app/        (uploaded files)
- .env               (configuration)
- public/uploads/    (if storing uploads here)

Via CloudPanel File Manager:
1. Select directories
2. Download as ZIP

Via SSH:
tar -czf backup-files-$(date +%Y%m%d).tar.gz storage .env public/uploads

Backup Best Practices:
- Daily automated database backups
- Weekly full file backups
- Store backups off-site (different server/cloud)
- Test restore procedures regularly
- Keep at least 7 daily + 4 weekly backups

================================================================================
                          Log Management
================================================================================

Application Logs:
Location: storage/logs/laravel.log

View Recent Errors:
tail -n 100 storage/logs/laravel.log

Follow Logs Live:
tail -f storage/logs/laravel.log

Search for Errors:
grep "ERROR" storage/logs/laravel.log

Log Rotation (daily logs):
- Set LOG_CHANNEL=daily in .env
- Set LOG_DAILY_DAYS=14 to keep 14 days
- Old logs auto-deleted

Manual Log Cleanup:
# Delete logs older than 7 days
find storage/logs -name "*.log" -mtime +7 -delete

Web Server Logs:
NGINX Access Log: /var/log/nginx/[site]-access.log
NGINX Error Log: /var/log/nginx/[site]-error.log

View NGINX Errors:
tail -n 50 /var/log/nginx/[site]-error.log

PHP-FPM Logs:
tail -f /var/log/php8.3-fpm.log

================================================================================
                          Cache Management
================================================================================

Clear All Caches:
php artisan optimize:clear

Clear Specific Caches:
php artisan config:clear    # Configuration cache
php artisan route:clear     # Route cache
php artisan view:clear      # Compiled views
php artisan cache:clear     # Application cache

Build Caches (Production):
php artisan config:cache
php artisan route:cache
php artisan view:cache

When to Clear Cache:
- After changing .env file
- After updating configuration files
- After adding new routes
- After code deployment
- When debugging issues

================================================================================
                          Database Maintenance
================================================================================

Run Migrations:
php artisan migrate

Rollback Last Migration:
php artisan migrate:rollback

Rollback All Migrations:
php artisan migrate:reset

Refresh Database (WARNING: Deletes all data):
php artisan migrate:fresh

Seed Database with Test Data:
php artisan db:seed

Check Database Connection:
php artisan db:show

Optimize Database (MySQL):
mysqlcheck -u [user] -p --optimize --all-databases

================================================================================
                          Performance Monitoring
================================================================================

Monitor Application Performance:

1. Enable Query Logging (temporarily):
   DB::enableQueryLog();
   // Your code
   dd(DB::getQueryLog());

2. Check Response Times:
   - Use browser DevTools Network tab
   - Monitor slow endpoints

3. Database Performance:
   - Review slow query log
   - Add indexes for frequently queried columns
   - Optimize N+1 queries

4. Cache Hit Rate:
   - Monitor cache effectiveness
   - Adjust cache duration

Server Resource Monitoring:

Check Disk Space:
df -h

Check Memory Usage:
free -m

Check CPU Usage:
top

Check PHP-FPM Status:
sudo systemctl status php8.3-fpm

Check MySQL Status:
sudo systemctl status mysql

================================================================================
                          Maintenance Mode
================================================================================

Enable Maintenance Mode:
php artisan down

With Custom Message:
php artisan down --message="We'll be back soon!" --retry=60

Allow Specific IPs:
php artisan down --allow=203.0.113.1 --allow=203.0.113.2

Render Custom View:
php artisan down --render="errors::503"

Disable Maintenance Mode:
php artisan up

Check Status:
# Application returns 503 when in maintenance mode

================================================================================
                          Security Maintenance
================================================================================

Regular Security Tasks:

1. Update Dependencies:
   composer update --with-all-dependencies
   (Test in staging first!)

2. Review Access Logs for Suspicious Activity:
   grep "POST /admin" /var/log/nginx/access.log

3. Check Failed Login Attempts:
   grep "failed login" storage/logs/laravel.log

4. Update PHP to Latest Patch Version:
   sudo apt update && sudo apt upgrade php8.3-fpm

5. Rotate API Keys Periodically:
   - Update third-party service keys
   - Regenerate APP_KEY if compromised

6. Review File Permissions:
   find . -type f -perm 0777  # Should return nothing
   find . -type d -perm 0777  # Should return nothing

================================================================================
                          Troubleshooting Quick Reference
================================================================================

Application Not Loading:
1. Check NGINX is running: sudo systemctl status nginx
2. Check PHP-FPM is running: sudo systemctl status php8.3-fpm
3. Review error logs: tail -f /var/log/nginx/error.log

500 Internal Server Error:
1. Check storage permissions: chmod -R 775 storage
2. Check .env exists and has APP_KEY
3. Review laravel.log: tail storage/logs/laravel.log

Database Connection Failed:
1. Verify DB credentials in .env
2. Test connection: php artisan db:show
3. Check MySQL is running: sudo systemctl status mysql

Queue Jobs Not Processing:
1. Check worker is running: sudo supervisorctl status
2. Check failed_jobs table: SELECT * FROM failed_jobs;
3. Restart workers: sudo supervisorctl restart laravel-worker:*

High CPU/Memory Usage:
1. Check for infinite loops in code
2. Review slow queries
3. Optimize cache settings
4. Consider upgrading server resources

For detailed troubleshooting, see TROUBLESHOOTING.txt

================================================================================
                          Routine Maintenance Schedule
================================================================================

Daily:
- Review error logs
- Monitor disk space
- Check backup completion

Weekly:
- Update packages (in staging)
- Review performance metrics
- Clean old logs
- Test backup restore

Monthly:
- Security updates
- Database optimization
- Review and update documentation
- Rotate SSL certificates (if manual)

Quarterly:
- Full security audit
- Performance optimization review
- Update dependencies to latest versions
- Infrastructure review

================================================================================

For configuration details, see CONFIGURATION.txt
For security best practices, see SECURITY.txt
For common issues, see TROUBLESHOOTING.txt