Troubleshooting - Webinoly

Verify Installation

System Verification

Run comprehensive system checks to identify issues:

webinoly -verify

This performs 7 verification tests:

Webinoly Integrity Test - Checks core files and configuration
NGINX Verification - Validates NGINX installation and configuration
PHP Verification - Checks PHP installation and settings
MySQL/MariaDB Verification - Validates database configuration
Service Status Verification - Ensures all services are running
Operating System Verification - Checks OS compatibility and settings
Additional Tools Verification - Validates optional tools installation

Critical Mode

Run only critical checks (faster, essential tests only):

webinoly -verify=critical

Check for Updates

Verify installation and check for available updates:

webinoly -verify -check-for-updates

Common Issues

NGINX Issues

NGINX Won’t Start

Symptoms:

NGINX service fails to start
Error messages about configuration

Solutions:

Test NGINX configuration:

sudo nginx -t

Check for syntax errors in site configurations:

for conf in /etc/nginx/sites-available/*; do
  echo "Checking $conf"
  sudo nginx -t -c $conf
done

Review NGINX error logs:

sudo tail -f /var/log/nginx/error.log

Reset NGINX configuration:

webinoly -server-reset=nginx
sudo systemctl restart nginx

Port Already in Use

Symptoms:

Error: “Address already in use”
NGINX fails to bind to port

Solutions:

Check what’s using the port:

sudo lsof -i :80
sudo lsof -i :443

Stop conflicting service:

sudo systemctl stop apache2  # if Apache is installed

Change tools port if conflict:

webinoly -tools-port=9999

SSL Certificate Issues

Symptoms:

SSL certificate errors
HTTPS not working

Solutions:

Check certificate files:

ls -la /etc/letsencrypt/live/example.com/

Test certificate renewal:

sudo certbot renew --dry-run

Regenerate certificate:

site example.com -ssl=off
site example.com -ssl=on

Check for orphan certificates:

webinoly -verify | grep "Orphan-Cert"

PHP Issues

PHP-FPM Not Running

Symptoms:

502 Bad Gateway errors
PHP pages not loading

Solutions:

Check PHP-FPM status:

sudo systemctl status php8.3-fpm

Check PHP error logs:

sudo tail -f /var/log/php8.3-fpm.log

Restart PHP-FPM:

sudo systemctl restart php8.3-fpm

Verify PHP socket exists:

ls -la /run/php/php-fpm.sock

Reset PHP configuration:

webinoly -server-reset=php

Memory Limit Issues

Symptoms:

“Allowed memory size exhausted” errors
PHP scripts timing out

Solutions:

Check current limits:

webinoly -info | grep -A 10 "\[PHP\]"

Increase PHP memory (requires manual edit):

sudo nano /etc/php/8.3/fpm/php.ini
# Modify: memory_limit = 256M
sudo systemctl restart php8.3-fpm

Adjust PHP workers if needed:

sudo nano /etc/php/8.3/fpm/pool.d/www.conf
# Adjust pm.max_children based on RAM
sudo systemctl restart php8.3-fpm

Upload Size Limits

Symptoms:

File uploads fail
“Maximum upload size exceeded” errors

Solutions:

Check current limits:

php -i | grep upload_max_filesize
php -i | grep post_max_size

Update both NGINX and PHP:

# Edit NGINX
sudo nano /etc/nginx/nginx.conf
# Set: client_max_body_size 100M;

# Edit PHP
sudo nano /etc/php/8.3/fpm/php.ini
# Set: upload_max_filesize = 100M
# Set: post_max_size = 100M

# Restart services
sudo systemctl reload nginx
sudo systemctl restart php8.3-fpm

MySQL/MariaDB Issues

Cannot Connect to MySQL

Symptoms:

“Access denied” errors
“Can’t connect to MySQL server”

Solutions:

Check MySQL is running:

sudo systemctl status mysql

Verify credentials:

webinoly -dbpass

Test connection:

mysql -u admin -p

Check MySQL error logs:

sudo tail -f /var/log/mysql/error.log

Restart MySQL:

sudo systemctl restart mysql

MySQL Won’t Start

Symptoms:

MySQL service fails to start
InnoDB recovery errors

Solutions:

Check disk space:

df -h

Review MySQL error log:

sudo tail -100 /var/log/mysql/error.log

Check for corrupted tables:

sudo mysqlcheck -u root -p --auto-repair --all-databases

Reset MySQL configuration:

webinoly -server-reset=mysql

Remote Access Not Working

Symptoms:

Cannot connect from remote host
Connection timeout errors

Solutions:

Verify public access is enabled:

webinoly -info | grep "Remote Access"

Check bind address:

sudo grep bind-address /etc/mysql/mysql.conf.d/*

Verify firewall rules:

sudo ufw status
sudo ufw allow 3306/tcp

Check user permissions:

mysql -u admin -p -e "SELECT User, Host FROM mysql.user;"

Cache Issues

Cache Not Working

Symptoms:

Pages not being cached
Cache headers missing

Solutions:

Verify cache is enabled:

site example.com -info | grep cache

Check cache directory:

ls -la /run/nginx-cache/

Clear cache:

webinoly -clear-cache=example.com

Check cache bypass settings:

grep -r "fastcgi_no_cache" /etc/nginx/common/

Redis Connection Failed

Symptoms:

Redis errors in logs
Object cache not working

Solutions:

Check Redis status:

sudo systemctl status redis-server

Test Redis connection:

redis-cli ping

Restart Redis:

sudo systemctl restart redis-server

Clear Redis cache:

webinoly -clear-cache=redis

Permission Issues

File Permission Errors

Symptoms:

“Permission denied” errors
Cannot write to files
Upload failures

Solutions:

Fix all permissions:

webinoly -server-reset=permissions

Fix specific site permissions:

sudo chown -R www-data:www-data /var/www/example.com
sudo find /var/www/example.com -type d -exec chmod 750 {} \;
sudo find /var/www/example.com -type f -exec chmod 640 {} \;

Check directory ownership:

ls -la /var/www/

Site Issues

Site Not Found (404)

Symptoms:

Site returns 404 error
“File not found” message

Solutions:

Verify site exists:

site example.com -info

Check site is enabled:

ls -la /etc/nginx/sites-enabled/example.com

Verify document root:

ls -la /var/www/example.com/htdocs/

Check NGINX configuration:

sudo nginx -t

White Screen / 500 Error

Symptoms:

Blank white page
HTTP 500 Internal Server Error

Solutions:

Check PHP error logs:

sudo tail -f /var/www/example.com/logs/error.log

Enable PHP error display (temporarily):

sudo nano /var/www/example.com/htdocs/wp-config.php
# Add: define('WP_DEBUG', true);

Check file permissions:

webinoly -server-reset=permissions

Clear all caches:

webinoly -clear-cache=all

Backup Issues

Backup Failed

Symptoms:

Backup command fails
Incomplete backups

Solutions:

Check disk space:

df -h

Verify backup tools:

which duplicity
which duply

Test S3 credentials:

webinoly -aws-s3-credentials

Check backup configuration:

cat ~/.duply/*/conf

Performance Issues

Slow Site Performance

Symptoms:

Pages load slowly
High server load

Solutions:

Check system resources:

webinoly -info
top
htop

Check disk I/O:

iostat -x 1

Review access logs for attacks:

sudo tail -f /var/www/example.com/logs/access.log

Enable caching if not already:

site example.com -cache=on

Check PHP workers:

webinoly -info | grep "pm.max_children"

High Memory Usage

Symptoms:

Server using too much RAM
OOM (Out of Memory) errors

Solutions:

Check memory usage:

free -h

Identify memory-hungry processes:

ps aux --sort=-%mem | head -n 10

Reduce PHP workers if needed:

sudo nano /etc/php/8.3/fpm/pool.d/www.conf
# Reduce pm.max_children

Increase SWAP:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

OS and System Issues

Running Out of Disk Space

Symptoms:

Disk usage over 75%
Services failing

Solutions:

Check disk usage:

df -h
du -sh /* | sort -h

Clear old logs:

sudo journalctl --vacuum-time=7d
sudo find /var/log -type f -name "*.gz" -delete

Clear package cache:

sudo apt clean
sudo apt autoremove

Check large files:

sudo find / -type f -size +100M -exec ls -lh {} \;

Unsupported OS Version

Symptoms:

Verify shows OS not supported
Installation fails

Solutions:

Check Ubuntu version:

lsb_release -a

Upgrade to supported version:

Ubuntu 24.04 LTS (recommended)
Ubuntu 22.04 LTS
Ubuntu 20.04 LTS (deprecated soon)

Configuration Issues

Configuration File Corrupted

Symptoms:

Webinoly commands fail
Version check errors

Solutions:

Regenerate configuration file:

webinoly -server-reset=confile

Check for duplicates:

grep -E "^([a-z\-]+):" /opt/webinoly/webinoly.conf | sort | uniq -d

Restore from backup:

sudo tar -xf ~/.webinoly-conf-restore_dont-remove -C /

Diagnostic Commands

Quick Health Check

# Run verification
webinoly -verify

# Check all services
sudo systemctl status nginx php8.3-fpm mysql redis-server memcached

# View system info
webinoly -info

Log Files

Important log locations:

# NGINX
/var/log/nginx/error.log
/var/log/nginx/access.log
/var/www/example.com/logs/error.log
/var/www/example.com/logs/access.log

# PHP
/var/log/php8.3-fpm.log

# MySQL
/var/log/mysql/error.log

# System
/var/log/syslog
sudo journalctl -xe

Network Diagnostics

# Check listening ports
sudo netstat -tlnp
sudo ss -tlnp

# Test connectivity
curl -I http://localhost
curl -I https://example.com

# Check DNS
dig example.com
nslookup example.com

Getting Help

If issues persist:

Run Verification: Always start with webinoly -verify
Check Logs: Review relevant log files
Test Configuration: Use sudo nginx -t
Reset Configuration: Try webinoly -server-reset
Community: Report issues at GitHub Issues

Before making system changes, always backup your data and configuration files.

Prevention

Best practices to avoid issues:

Regular backups with webinoly -backup
Keep system updated with webinoly -update
Monitor disk space regularly
Run webinoly -verify after changes
Review logs periodically
Use staging environment for testing
Document custom configurations
Keep emergency recovery plan

Next Steps

Server Management - Configure server settings
Updates - Update Webinoly and stack
Uninstall - Remove Webinoly if needed

Get Started

Core Concepts

Managing Sites

Stack Management

Advanced Features

Operations

​Verify Installation

​System Verification

​Critical Mode

​Check for Updates

​Common Issues

​NGINX Issues

​NGINX Won’t Start

​Port Already in Use

​SSL Certificate Issues

​PHP Issues

​PHP-FPM Not Running

​Memory Limit Issues

​Upload Size Limits

​MySQL/MariaDB Issues

​Cannot Connect to MySQL

​MySQL Won’t Start

​Remote Access Not Working

​Cache Issues

​Cache Not Working

​Redis Connection Failed

​Permission Issues

​File Permission Errors

​Site Issues

​Site Not Found (404)

​White Screen / 500 Error

​Backup Issues

​Backup Failed

​Performance Issues

​Slow Site Performance

​High Memory Usage

​OS and System Issues

​Running Out of Disk Space

​Unsupported OS Version

​Configuration Issues

​Configuration File Corrupted

​Diagnostic Commands

​Quick Health Check

​Log Files

​Network Diagnostics

​Getting Help

​Prevention

​Next Steps

Build docs developers (and LLMs) love

Verify Installation

System Verification

Critical Mode

Check for Updates

Common Issues

NGINX Issues

NGINX Won’t Start

Port Already in Use

SSL Certificate Issues

PHP Issues

PHP-FPM Not Running

Memory Limit Issues

Upload Size Limits

MySQL/MariaDB Issues

Cannot Connect to MySQL

MySQL Won’t Start

Remote Access Not Working

Cache Issues

Cache Not Working

Redis Connection Failed

Permission Issues

File Permission Errors

Site Issues

Site Not Found (404)

White Screen / 500 Error

Backup Issues

Backup Failed

Performance Issues

Slow Site Performance

High Memory Usage

OS and System Issues

Running Out of Disk Space

Unsupported OS Version

Configuration Issues

Configuration File Corrupted

Diagnostic Commands

Quick Health Check

Log Files

Network Diagnostics

Getting Help

Prevention

Next Steps