🔧 PUQcloud Troubleshooting Guide

Comprehensive guide for diagnosing and resolving issues with PUQcloud installation and operation.

🚨 Common Issues by Category

1. 🔑 Access Rights and Permissions

Problem: "Permission denied" when accessing files

# Check file ownership
ls -la /var/www/puqcloud/

# Expected result:
drwxr-xr-x www-data www-data /var/www/puqcloud/

Solution:

# Fix ownership
sudo chown -R www-data:www-data /var/www/puqcloud

# Fix permissions
sudo chmod -R 755 /var/www/puqcloud
sudo chmod -R 775 /var/www/puqcloud/storage
sudo chmod -R 775 /var/www/puqcloud/bootstrap/cache

Problem: FTP user cannot access files

# Check user group membership
groups ftp_username

# Expected result: ftp_username : ftp_username www-data

Solution:

# Add user to www-data group
sudo usermod -aG www-data ftp_username

# Set group permissions
sudo chmod -R g+w /var/www/puqcloud

2. 🗄️ Database Issues

Problem: "Connection refused" to database

# Check MySQL status
systemctl status mariadb
systemctl status mysql

# Check listening ports
netstat -tlnp | grep 3306

Solution:

# Start MySQL service
sudo systemctl start mariadb
sudo systemctl enable mariadb

# Check MySQL configuration
sudo mysql -u root -p -e "SELECT VERSION();"

Problem: Database user cannot connect

# Check user existence
mysql -u root -p -e "SELECT User, Host FROM mysql.user WHERE User LIKE 'puqcloud%';"

# Check user privileges
mysql -u root -p -e "SHOW GRANTS FOR 'puqcloud_user_xxx'@'localhost';"

Solution:

# Recreate user with proper privileges
mysql -u root -p << EOF
CREATE USER 'new_user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON database_name.* TO 'new_user'@'localhost';
FLUSH PRIVILEGES;
EOF

Problem: Migration errors

# Check migration status
php artisan migrate:status

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

Solution:

# Reset migrations
php artisan migrate:fresh --seed

# Or rollback and rerun
php artisan migrate:rollback
php artisan migrate

3. 🌐 Web Server (Nginx) Issues

Problem: 502 Bad Gateway error

# Check Nginx status
systemctl status nginx

# Check PHP-FPM status
systemctl status php8.2-fpm

# Check Nginx logs
tail -f /var/log/nginx/error.log

Solution:

# Restart services
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

# Check PHP-FPM socket
ls -la /run/php/php8.2-fpm.sock

Problem: 404 errors for static files

# Check Nginx configuration
nginx -t

# Check site configuration
cat /etc/nginx/sites-enabled/default

Solution:

# Verify document root
sudo nano /etc/nginx/sites-available/default
# Ensure: root /var/www/puqcloud/public;

# Test configuration and reload
sudo nginx -t && sudo systemctl reload nginx

Problem: SSL certificate issues

# Check certificate status
certbot certificates

# Check certificate validity
openssl x509 -in /etc/letsencrypt/live/domain.com/fullchain.pem -text -noout | grep "Not After"

Solution:

# Renew certificate
sudo certbot renew --force-renewal

# Or recreate certificate
sudo certbot --nginx -d your-domain.com --force-renewal

4. 🔐 SSL and HTTPS Issues

Problem: Mixed content warnings

# Check APP_URL in .env
grep APP_URL /var/www/puqcloud/.env

# Should be: APP_URL=https://your-domain.com

Solution:

# Update .env file
sed -i 's|APP_URL=http://|APP_URL=https://|' /var/www/puqcloud/.env

# Clear cache
php artisan config:clear
php artisan cache:clear

Problem: Certificate not trusted

# Check certificate chain
openssl s_client -connect your-domain.com:443 -servername your-domain.com

Solution:

# For Let's Encrypt certificates
sudo certbot --nginx -d your-domain.com

# For self-signed certificates
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/nginx-selfsigned.key \
  -out /etc/ssl/certs/nginx-selfsigned.crt \
  -subj "/CN=your-domain.com"

5. 📧 Email Issues

Problem: Emails not sending

# Check sendmail status
which sendmail
systemctl status sendmail

# Check PHP mail configuration
php -m | grep mail

Solution:

# Install/restart sendmail
sudo apt install -y sendmail
sudo systemctl restart sendmail

# Test email sending
echo "Test email" | sendmail your-email@domain.com

Problem: Emails going to spam

# Check mail logs
tail -f /var/log/mail.log

# Check domain reputation
dig TXT your-domain.com

Solution:

# Configure SPF record (add to DNS)
# TXT record: "v=spf1 ip4:YOUR-SERVER-IP ~all"

# Configure proper hostname
hostnamectl set-hostname your-domain.com

6. 🐘 PHP Issues

Problem: PHP extensions missing

# Check loaded extensions
php -m | grep -E "xml|dom|mysql|redis"

# Check PHP version
php -v

Solution:

# Install missing extensions
sudo apt install -y php8.2-xml php8.2-dom php8.2-mysql php8.2-redis

# Restart PHP-FPM
sudo systemctl restart php8.2-fpm

Problem: Memory limit exceeded

# Check current limits
php -i | grep memory_limit

# Check error logs
tail -f /var/log/php_errors.log

Solution:

# Increase PHP memory limit
sudo sed -i 's/memory_limit = .*/memory_limit = 512M/' /etc/php/8.2/fpm/php.ini
sudo sed -i 's/memory_limit = .*/memory_limit = 512M/' /etc/php/8.2/cli/php.ini

# Restart PHP-FPM
sudo systemctl restart php8.2-fpm

7. 🔄 Horizon (Queue) Issues

Problem: Horizon not running

# Check Horizon status
php artisan horizon:status

# Check Supervisor status
sudo supervisorctl status horizon

Solution:

# Restart Horizon
sudo supervisorctl restart horizon

# Or restart Supervisor
sudo systemctl restart supervisor

Problem: Jobs failing

# Check failed jobs
php artisan queue:failed

# Check Horizon logs
tail -f /var/www/puqcloud/storage/logs/horizon.log

Solution:

# Clear failed jobs
php artisan queue:flush

# Restart Horizon
php artisan horizon:terminate
sudo supervisorctl restart horizon

Problem: Horizon configuration errors

# Check Supervisor configuration
cat /etc/supervisor/conf.d/horizon.conf

# Check process status
ps aux | grep horizon

Solution:

# Recreate Supervisor configuration
sudo tee /etc/supervisor/conf.d/horizon.conf << EOF
[program:horizon]
process_name=%(program_name)s
command=php /var/www/puqcloud/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/puqcloud/storage/logs/horizon.log
EOF

# Update Supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

8. 📁 File System Issues

Problem: Disk space full

# Check disk usage
df -h
du -sh /var/www/puqcloud/storage/logs/*

Solution:

# Clean old logs
sudo find /var/www/puqcloud/storage/logs/ -name "*.log" -mtime +7 -delete

# Clean system logs
sudo journalctl --vacuum-time=7d

# Clean package cache
sudo apt autoremove && sudo apt autoclean

Problem: Upload directory not writable

# Check upload directories
ls -la /var/www/puqcloud/storage/
ls -la /var/www/puqcloud/public/uploads/

Solution:

# Create and set permissions for upload directories
sudo mkdir -p /var/www/puqcloud/storage/uploads
sudo mkdir -p /var/www/puqcloud/public/uploads
sudo chown -R www-data:www-data /var/www/puqcloud/storage/
sudo chown -R www-data:www-data /var/www/puqcloud/public/uploads/
sudo chmod -R 775 /var/www/puqcloud/storage/
sudo chmod -R 775 /var/www/puqcloud/public/uploads/

🔍 Diagnostic Commands

System Information

# OS version
lsb_release -a

# System resources
free -h
df -h
top

# Network interfaces
ip addr show

# Open ports
netstat -tlnp

Service Status

# All PUQcloud services
systemctl status nginx php8.2-fpm mariadb redis-server supervisor

# Service logs
journalctl -u nginx -f
journalctl -u php8.2-fpm -f
journalctl -u mariadb -f

Laravel Specific

# Application status
php artisan about

# Cache status
php artisan config:show
php artisan route:list

# Queue status
php artisan queue:work --once --timeout=10

🧰 Diagnostic Script

Create automated diagnostic script:

#!/bin/bash
# PUQcloud Diagnostic Script

echo "=== PUQcloud System Diagnostics ==="
echo "Date: $(date)"
echo "Hostname: $(hostname)"
echo

# Check services
echo "=== Service Status ==="
for service in nginx php8.2-fpm mariadb redis-server supervisor; do
    if systemctl is-active --quiet $service; then
        echo "✅ $service: Running"
    else
        echo "❌ $service: Not running"
    fi
done
echo

# Check disk space
echo "=== Disk Usage ==="
df -h | grep -E "(Filesystem|/dev/)"
echo

# Check memory
echo "=== Memory Usage ==="
free -h
echo

# Check PHP
echo "=== PHP Status ==="
php -v | head -1
echo "Extensions: $(php -m | grep -E 'xml|mysql|redis|curl' | tr '\n' ' ')"
echo

# Check database connection
echo "=== Database Connection ==="
if mysql -e "SELECT 1" 2>/dev/null; then
    echo "✅ Database: Connected"
else
    echo "❌ Database: Connection failed"
fi
echo

# Check web server response
echo "=== Web Server Response ==="
if curl -s -o /dev/null -w "%{http_code}" http://localhost | grep -q 200; then
    echo "✅ Web server: Responding"
else
    echo "❌ Web server: Not responding"
fi
echo

# Check Horizon
echo "=== Horizon Status ==="
cd /var/www/puqcloud 2>/dev/null && php artisan horizon:status 2>/dev/null || echo "❌ Horizon: Not accessible"
echo

echo "=== End of Diagnostics ==="

Save as /usr/local/bin/puqcloud-diagnostics and make executable:

sudo chmod +x /usr/local/bin/puqcloud-diagnostics

📞 Getting Help

Log Files to Check

# Application logs
/var/www/puqcloud/storage/logs/laravel.log

# Web server logs
/var/log/nginx/access.log
/var/log/nginx/error.log

# PHP logs
/var/log/php_errors.log

# System logs
/var/log/syslog
/var/log/auth.log

# Database logs
/var/log/mysql/error.log

# Horizon logs
/var/www/puqcloud/storage/logs/horizon.log

Information to Provide When Asking for Help

System Information:

lsb_release -a
php -v
nginx -v
mysql --version

Error Messages:
- Exact error text
- When the error occurs
- What action triggers it

Log Excerpts:

# Last 50 lines from relevant log
tail -50 /var/log/nginx/error.log

Configuration:

# Sanitized configuration (remove passwords)
grep -v "password\|secret" /var/www/puqcloud/.env

Support Channels

GitHub Issues: PUQcloud Issues
Documentation: doc.puq.info
Community Forum: forum.puqcloud.com

Emergency Recovery

If system is completely broken:

# 1. Backup current state
sudo tar -czf puqcloud_broken_$(date +%Y%m%d).tar.gz /var/www/puqcloud

# 2. Restore from backup (if available)
# sudo tar -xzf puqcloud_backup_DATE.tar.gz -C /

# 3. Or reinstall from scratch
sudo ./delete_and_clear_databases.sh  # If needed
sudo ./install.sh your-domain.com admin@domain.com password "Admin Name"

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

🔧 PUQcloud Troubleshooting Guide

🚨 Common Issues by Category

1. 🔑 Access Rights and Permissions

Problem: "Permission denied" when accessing files

Problem: FTP user cannot access files

2. 🗄️ Database Issues

Problem: "Connection refused" to database

Problem: Database user cannot connect

Problem: Migration errors

3. 🌐 Web Server (Nginx) Issues

Problem: 502 Bad Gateway error

Problem: 404 errors for static files

Problem: SSL certificate issues

4. 🔐 SSL and HTTPS Issues

Problem: Mixed content warnings

Problem: Certificate not trusted

5. 📧 Email Issues

Problem: Emails not sending

Problem: Emails going to spam

6. 🐘 PHP Issues

Problem: PHP extensions missing

Problem: Memory limit exceeded

7. 🔄 Horizon (Queue) Issues

Problem: Horizon not running

Problem: Jobs failing

Problem: Horizon configuration errors

8. 📁 File System Issues

Problem: Disk space full

Problem: Upload directory not writable

🔍 Diagnostic Commands

System Information

Service Status

Laravel Specific

🧰 Diagnostic Script

📞 Getting Help

Log Files to Check

Information to Provide When Asking for Help

Support Channels

Emergency Recovery