Add comprehensive detection troubleshooting guide

DOCUMENTATION:
- DETECTION_TROUBLESHOOTING.md: Complete troubleshooting guide
- How detection works step-by-step
- Common issues on AlmaLinux, CentOS, Ubuntu, Debian
- OS-specific solutions and file paths
- Diagnostic commands and usage examples

COVERS:
- Quick start: How to check what was detected
- Specific issues: Apache, MySQL, Nginx, Firewall not detected
- Silent detection problems (cache-related)
- Advanced debugging and manual testing
- How to report detection issues

QUICK REFERENCE:
  bash launcher.sh --detect-only     # Check what was detected
  bash test-detection.sh              # Full diagnostic
  bash test-detection.sh verbose      # Detailed diagnostic

DETECTION_TROUBLESHOOTING.md

@@ -0,0 +1,354 @@
+# System Detection Troubleshooting Guide
+
+## Overview
+
+The Server Toolkit automatically detects your system configuration on startup:
+- Operating System (CentOS, AlmaLinux, Rocky Linux, Ubuntu, Debian, etc.)
+- Control Panel (cPanel, Plesk, InterWorx, or Standalone)
+- Web Server (Apache/httpd, Nginx, LiteSpeed, etc.)
+- Database (MySQL, MariaDB, PostgreSQL)
+- Firewall (CSF, firewalld, iptables, UFW)
+- PHP versions available on system
+
+If you're not seeing these detected correctly, use these diagnostic tools.
+
+---
+
+## Quick Start: Test Detection
+
+### Option 1: Check What Was Detected (Fastest)
+
+```bash
+bash launcher.sh --detect-only
+```
+
+This shows your current system configuration in a clean format:
+```
+Control Panel:      cpanel 11.134.0.11
+Operating System:   almalinux 9.7
+Web Server:         apache 2.4.66
+Database:           mariadb 10.6.25
+Firewall:           csf 16.12 (no)
+PHP Versions:       8.0.30 8.1.34 8.2.30
+```
+
+### Option 2: Run Full Diagnostic (More Detailed)
+
+```bash
+bash test-detection.sh
+```
+
+This performs step-by-step testing:
+- [STEP 1] Tests if commands exist on system
+- [STEP 2] Attempts version detection for each service
+- [STEP 3] Tests control panel detection
+- [STEP 4] Tests OS detection
+- [STEP 5] Tests firewall detection
+- [STEP 6] Runs full system detection
+- [STEP 7] Displays detected variables
+- [STEP 8] Summary with warnings
+
+### Option 3: Verbose Diagnostic (Maximum Detail)
+
+```bash
+bash test-detection.sh verbose
+```
+
+Same as above, but also shows file paths and exact locations where services were found.
+
+---
+
+## Specific Issues & Solutions
+
+### Issue: Apache/httpd Not Detected
+
+**Test:**
+```bash
+which httpd
+httpd -v
+```
+
+**If httpd is not found:**
+- Apache/httpd may not be installed
+- Check: `yum list installed | grep httpd` (RHEL/CentOS/AlmaLinux)
+- Check: `apt list --installed | grep apache2` (Ubuntu/Debian)
+
+**If httpd exists but not detected:**
+1. Run diagnostic: `bash test-detection.sh`
+2. Check STEP 1 output for "✓ Apache (httpd)"
+3. If found but not detected in STEP 6, report the issue
+
+**On AlmaLinux/Rocky (IMPORTANT):**
+- AlmaLinux uses `httpd` (not `apache2` like Debian)
+- Toolkit checks for BOTH, so this should work
+- If still not working, verify: `command -v httpd`
+
+---
+
+### Issue: MySQL/MariaDB Not Detected
+
+**Test:**
+```bash
+which mysql
+mysql --version
+```
+
+**If mysql is not found:**
+- MySQL/MariaDB may not be installed
+- Check: `yum list installed | grep -i mysql` (RHEL-based)
+- Check: `apt list --installed | grep mysql` (Debian-based)
+
+**If mysql exists but not detected:**
+1. Run: `bash test-detection.sh verbose`
+2. Check STEP 2 "MySQL/MariaDB Version Detection" output
+3. Verify output of: `mysql --version`
+4. If command works but detection fails, report issue
+
+---
+
+### Issue: Nginx/Apache Both Missing
+
+**On Standalone Servers:**
+- Web server MUST be installed for most toolkit features
+- Install Apache: `yum install httpd` or `apt install apache2`
+- Install Nginx: `yum install nginx` or `apt install nginx`
+
+**Verify installation:**
+```bash
+bash launcher.sh --detect-only
+```
+
+---
+
+### Issue: Firewall Not Detected
+
+**Possible causes:**
+1. No firewall installed (acceptable on standalone)
+2. Firewall installed but toolkit doesn't detect it yet
+
+**Check available firewalls:**
+```bash
+# CSF (ConfigServer Firewall)
+[ -f /etc/csf/csf.conf ] && echo "CSF found" || echo "CSF not found"
+
+# firewalld
+command -v firewall-cmd && echo "firewalld found" || echo "firewalld not found"
+
+# iptables
+command -v iptables && echo "iptables found" || echo "iptables not found"
+
+# UFW (Ubuntu)
+command -v ufw && echo "UFW found" || echo "UFW not found"
+```
+
+---
+
+### Issue: Control Panel Not Detected on Standalone
+
+**This is NORMAL** - standalone servers have no control panel.
+
+Expected output:
+```
+Control Panel:      none
+```
+
+The toolkit should still work fine with:
+- `SYS_LOG_DIR="/var/log/apache2"` (or `/var/log/httpd`)
+- `SYS_USER_HOME_BASE="/home"`
+
+---
+
+### Issue: OS Not Detected
+
+**Test:**
+```bash
+cat /etc/os-release
+# or
+cat /etc/redhat-release
+```
+
+**Supported OSes:**
+- ✅ CentOS 7, 8, 9
+- ✅ AlmaLinux 8, 9
+- ✅ Rocky Linux 8, 9
+- ✅ CloudLinux 7, 8, 9
+- ✅ Ubuntu 20.04, 22.04, 24.04
+- ✅ Debian 11, 12
+
+If your OS isn't showing, it may not be in the detection list.
+
+---
+
+## How Detection Works
+
+### Detection Sequence
+
+1. **Common Functions Loaded** (`lib/common-functions.sh`)
+   - Defines helper functions like `command_exists`
+   - Defines print functions for output
+
+2. **System Detect Library Loaded** (`lib/system-detect.sh`)
+   - Detects control panel (`/usr/local/cpanel/version`, etc.)
+   - Detects OS (`/etc/os-release`)
+   - Detects web server (checks for `httpd`, `apache2`, `nginx`, etc.)
+   - Detects database (`mysql --version`)
+   - Detects PHP versions
+   - Detects firewall (CSF, firewalld, iptables, UFW)
+
+3. **Variables Set**
+   - `SYS_CONTROL_PANEL`: cpanel, plesk, interworx, or none
+   - `SYS_OS_TYPE`: almalinux, ubuntu, etc.
+   - `SYS_WEB_SERVER`: apache, nginx, litespeed, or unknown
+   - `SYS_DB_TYPE`: mysql, mariadb, postgresql, or none
+   - `SYS_FIREWALL`: csf, firewalld, iptables, ufw, or none
+   - `SYS_PHP_VERSIONS`: Array of detected PHP versions
+   - `SYS_DETECTION_COMPLETE`: Set to "yes" when done
+
+4. **Detection Cached**
+   - Results cached in `.sysref.beta`
+   - Cache expires after 1 hour
+   - Cache prevents re-detection on subsequent runs
+   - Force refresh with: `bash launcher.sh --detect-only`
+
+---
+
+## Silent Detection Issues
+
+### Why You Might Not See Detection Output
+
+**Issue:** You run the toolkit, but don't see what was detected.
+
+**Cause:** Detection output only shows when cache needs rebuilding (first run or after 1 hour).
+
+**Solution:** Use diagnostic tools:
+```bash
+# See what WAS detected (even if cache is fresh)
+bash launcher.sh --detect-only
+
+# Run full diagnostic
+bash test-detection.sh
+```
+
+---
+
+## Debugging Tips
+
+### Enable Verbose Output
+
+Run diagnostic with `verbose` flag:
+```bash
+bash test-detection.sh verbose
+```
+
+Shows:
+- Exact file paths where services found
+- Version command outputs
+- All detection attempts
+
+### Check Individual Services
+
+Test command availability:
+```bash
+bash -c 'source lib/common-functions.sh; command_exists httpd && echo "httpd found" || echo "httpd NOT found"'
+```
+
+### Manual Detection Testing
+
+```bash
+# Load detection library
+source lib/system-detect.sh
+
+# Run individual detections
+detect_control_panel
+detect_os
+detect_web_server
+detect_database
+detect_firewall
+
+# Check results
+echo "Web Server: $SYS_WEB_SERVER"
+echo "Database: $SYS_DB_TYPE"
+echo "Firewall: $SYS_FIREWALL"
+```
+
+---
+
+## Common Issues on Specific OSes
+
+### AlmaLinux / Rocky Linux
+
+**Apache Binary Name:**
+- Uses `httpd` (not `apache2`)
+- Toolkit checks for BOTH, so should work
+- Verify: `which httpd`
+
+**MySQL/MariaDB:**
+- Usually comes pre-installed
+- Check: `rpm -qa | grep -i mariadb`
+
+**File Paths:**
+- Logs: `/var/log/apache2/domlogs` (cPanel) or `/var/log/httpd/`
+- Apache config: `/etc/httpd/conf/`
+
+### Ubuntu / Debian
+
+**Apache Binary Name:**
+- Uses `apache2` (not `httpd`)
+- Toolkit checks for BOTH, so should work
+- Verify: `which apache2`
+
+**MySQL/MariaDB:**
+- Usually comes pre-installed
+- Check: `dpkg -l | grep -i mysql`
+
+**File Paths:**
+- Logs: `/var/log/apache2/`
+- MySQL socket: `/var/run/mysqld/mysqld.sock` (not `/var/lib/mysql/mysql.sock`)
+
+---
+
+## Advanced: Clear Cache and Force Re-detection
+
+If detection seems stuck with old values:
+
+```bash
+# Method 1: Use diagnostic tool (forces fresh detection)
+bash launcher.sh --detect-only
+
+# Method 2: Manually clear cache and run launcher
+rm -f .sysref.beta .sysref.beta.timestamp
+bash launcher.sh
+```
+
+---
+
+## Report a Detection Issue
+
+If detection still fails after trying these steps:
+
+1. Run full diagnostic:
+   ```bash
+   bash test-detection.sh verbose > /tmp/detection-report.txt 2>&1
+   cat /tmp/detection-report.txt
+   ```
+
+2. Include output showing:
+   - Which services exist but aren't detected
+   - What commands work manually but fail in detection
+   - Your OS type and version
+
+---
+
+## Summary
+
+| Command | When to Use |
+|---------|------------|
+| `bash launcher.sh --detect-only` | Quick check of detected config |
+| `bash test-detection.sh` | Full diagnostic with step-by-step testing |
+| `bash test-detection.sh verbose` | Detailed diagnostic with paths and outputs |
+| `rm -f .sysref.beta*; bash launcher.sh` | Force fresh detection and rebuild cache |
+
+---
+
+**Last Updated:** 2026-03-20
+**Tested On:** AlmaLinux 9.7, CentOS 9, Ubuntu 22.04

launcher.sh

@@ -732,6 +732,13 @@ startup_detection() {
         if ! read -p "Press Enter to continue..." </dev/tty 2>/dev/null; then
             true  # Continue even if read fails
         fi
+    else
+        # Database is cached and fresh, but still ensure detection was completed
+        # (this addresses issue where detection output not shown on cached runs)
+        if [ -z "${SYS_DETECTION_COMPLETE:-}" ]; then
+            print_error "System detection failed - please check system configuration"
+            return 1
+        fi
     fi
 }
 
@@ -740,6 +747,50 @@ startup_detection() {
 #############################################################################
 
 main() {
+    # Handle command-line arguments
+    case "${1:-}" in
+        --detect-only|--check-detection)
+            # Initialize directories
+            init_directories || {
+                echo "ERROR: Failed to initialize directories"
+                return 1
+            }
+
+            # Force fresh detection regardless of cache
+            echo "Forcing system re-detection..."
+            echo ""
+            rm -f "$BASE_DIR/.sysref.beta" "$BASE_DIR/.sysref.beta.timestamp" 2>/dev/null || true
+
+            # Run detection
+            initialize_system_detection
+
+            # Show results
+            echo ""
+            echo "═══════════════════════════════════════════════════════════════"
+            echo "                    DETECTION RESULTS"
+            echo "═══════════════════════════════════════════════════════════════"
+            echo ""
+            echo "Control Panel:      ${SYS_CONTROL_PANEL:-unknown} ${SYS_CONTROL_PANEL_VERSION:-}"
+            echo "Operating System:   ${SYS_OS_TYPE:-unknown} ${SYS_OS_VERSION:-}"
+            echo "Web Server:         ${SYS_WEB_SERVER:-unknown} ${SYS_WEB_SERVER_VERSION:-}"
+            echo "Database:           ${SYS_DB_TYPE:-unknown} ${SYS_DB_VERSION:-}"
+            echo "Firewall:           ${SYS_FIREWALL:-unknown} ${SYS_FIREWALL_VERSION:-} (${SYS_FIREWALL_ACTIVE:-unknown})"
+            echo "PHP Versions:       ${SYS_PHP_VERSIONS[*]:-none detected}"
+            echo ""
+            echo "═══════════════════════════════════════════════════════════════"
+            return 0
+            ;;
+        --help|--usage|-h|-?)
+            echo "Usage: launcher.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --detect-only        Show system detection results and exit"
+            echo "  --help               Show this help message"
+            echo ""
+            return 0
+            ;;
+    esac
+
     # Initialize directories once at startup
     init_directories || {
         echo "ERROR: Failed to initialize directories"

test-detection.sh

@@ -0,0 +1,256 @@
+#!/bin/bash
+#############################################################################
+# System Detection Diagnostic Tool
+# Run this on a standalone server to test all detection functions
+# Usage: bash test-detection.sh [verbose]
+#############################################################################
+
+set -eo pipefail
+
+BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$BASE_DIR/lib"
+
+# Check for verbose flag
+VERBOSE=0
+[ "$1" = "verbose" ] && VERBOSE=1
+
+# Load libraries
+source "$LIB_DIR/common-functions.sh"
+source "$LIB_DIR/system-detect.sh"
+
+echo "═══════════════════════════════════════════════════════════════"
+echo "              SYSTEM DETECTION DIAGNOSTIC TOOL"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+
+#############################################################################
+# STEP 1: Test Basic Commands
+#############################################################################
+
+echo "[STEP 1] Testing Command Availability"
+echo "─────────────────────────────────────────────────────────────"
+
+test_command() {
+    local cmd="$1"
+    local desc="$2"
+
+    if command_exists "$cmd"; then
+        local path=$(which "$cmd" 2>/dev/null)
+        echo "✓ $desc"
+        [ $VERBOSE -eq 1 ] && echo "  Location: $path"
+    else
+        echo "✗ $desc - NOT FOUND"
+    fi
+}
+
+echo ""
+echo "Web Servers:"
+test_command "httpd" "Apache (httpd)"
+test_command "apache2" "Apache (apache2)"
+test_command "nginx" "Nginx"
+
+echo ""
+echo "Databases:"
+test_command "mysql" "MySQL/MariaDB"
+test_command "psql" "PostgreSQL"
+
+echo ""
+echo "Firewalls:"
+test_command "firewall-cmd" "Firewalld"
+test_command "iptables" "iptables"
+test_command "ufw" "UFW"
+
+#############################################################################
+# STEP 2: Test Version Detection
+#############################################################################
+
+echo ""
+echo "[STEP 2] Version Detection"
+echo "─────────────────────────────────────────────────────────────"
+
+echo ""
+echo "Apache Version Detection:"
+if command_exists httpd; then
+    httpd_v=$(httpd -v 2>/dev/null | grep -oP 'Apache/\K[\d.]+' | head -1)
+    echo "✓ httpd version: $httpd_v"
+elif command_exists apache2; then
+    apache2_v=$(apache2 -v 2>/dev/null | grep -oP 'Apache/\K[\d.]+' | head -1)
+    echo "✓ apache2 version: $apache2_v"
+else
+    echo "✗ Apache not found"
+fi
+
+echo ""
+echo "MySQL/MariaDB Version Detection:"
+if command_exists mysql; then
+    mysql_v=$(mysql --version 2>/dev/null)
+    echo "✓ mysql version: $mysql_v"
+else
+    echo "✗ MySQL not found"
+fi
+
+echo ""
+echo "Nginx Version Detection:"
+if command_exists nginx; then
+    nginx_v=$(nginx -v 2>&1 | grep -oP 'nginx/\K[\d.]+' 2>/dev/null)
+    echo "✓ nginx version: $nginx_v"
+else
+    echo "✗ Nginx not found"
+fi
+
+#############################################################################
+# STEP 3: Test Control Panel Detection
+#############################################################################
+
+echo ""
+echo "[STEP 3] Control Panel Detection"
+echo "─────────────────────────────────────────────────────────────"
+
+echo ""
+if [ -f "/usr/local/cpanel/version" ]; then
+    cpanel_v=$(cat /usr/local/cpanel/version)
+    echo "✓ cPanel detected: v$cpanel_v"
+elif [ -f "/usr/local/psa/version" ]; then
+    plesk_v=$(cat /usr/local/psa/version | head -1)
+    echo "✓ Plesk detected: v$plesk_v"
+elif [ -d "/usr/local/interworx" ] || [ -f "/etc/interworx/iworx.ini" ]; then
+    echo "✓ InterWorx detected"
+else
+    echo "✓ Standalone (no control panel)"
+fi
+
+#############################################################################
+# STEP 4: Test OS Detection
+#############################################################################
+
+echo ""
+echo "[STEP 4] Operating System Detection"
+echo "─────────────────────────────────────────────────────────────"
+
+if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    echo "✓ OS Detected: $NAME"
+    echo "  Version: $VERSION_ID"
+else
+    echo "✗ Could not detect OS"
+fi
+
+#############################################################################
+# STEP 5: Test Firewall Detection
+#############################################################################
+
+echo ""
+echo "[STEP 5] Firewall Detection"
+echo "─────────────────────────────────────────────────────────────"
+
+echo ""
+if [ -f "/etc/csf/csf.conf" ]; then
+    csf_v=$(head -1 /etc/csf/version.txt 2>/dev/null || echo "unknown")
+    echo "✓ CSF detected: v$csf_v"
+    if pgrep -x lfd > /dev/null 2>&1; then
+        echo "  Status: ACTIVE"
+    else
+        echo "  Status: INACTIVE"
+    fi
+else
+    echo "✗ CSF not found"
+fi
+
+echo ""
+if command_exists firewall-cmd; then
+    fw_v=$(firewall-cmd --version 2>/dev/null || echo "unknown")
+    echo "✓ firewalld detected: v$fw_v"
+    if systemctl is-active --quiet firewalld 2>/dev/null; then
+        echo "  Status: ACTIVE"
+    else
+        echo "  Status: INACTIVE"
+    fi
+else
+    echo "✗ firewalld not found"
+fi
+
+echo ""
+if command_exists iptables; then
+    ipt_v=$(iptables --version 2>/dev/null | grep -oP 'v\K[\d.]+' | head -1 || echo "unknown")
+    echo "✓ iptables detected: v$ipt_v"
+    rules=$(iptables -L INPUT -n 2>/dev/null | wc -l)
+    if [ "$rules" -gt 2 ]; then
+        echo "  Status: ACTIVE ($(($rules - 2)) rules)"
+    else
+        echo "  Status: NO RULES"
+    fi
+else
+    echo "✗ iptables not found"
+fi
+
+#############################################################################
+# STEP 6: Run Full Detection
+#############################################################################
+
+echo ""
+echo "[STEP 6] Running Full System Detection"
+echo "─────────────────────────────────────────────────────────────"
+echo ""
+
+# Run the full detection
+initialize_system_detection
+
+#############################################################################
+# STEP 7: Display Detected System Variables
+#############################################################################
+
+echo ""
+echo "[STEP 7] Detected System Variables"
+echo "─────────────────────────────────────────────────────────────"
+echo ""
+
+echo "Control Panel:     ${SYS_CONTROL_PANEL:-unknown}"
+echo "Control Panel Ver: ${SYS_CONTROL_PANEL_VERSION:-N/A}"
+echo "Operating System:  ${SYS_OS_TYPE:-unknown}"
+echo "OS Version:        ${SYS_OS_VERSION:-N/A}"
+echo "Web Server:        ${SYS_WEB_SERVER:-unknown}"
+echo "Web Server Ver:    ${SYS_WEB_SERVER_VERSION:-N/A}"
+echo "Database Type:     ${SYS_DB_TYPE:-unknown}"
+echo "Database Ver:      ${SYS_DB_VERSION:-N/A}"
+echo "Log Directory:     ${SYS_LOG_DIR:-N/A}"
+echo "User Home Base:    ${SYS_USER_HOME_BASE:-N/A}"
+echo "PHP Versions:      ${SYS_PHP_VERSIONS[*]:-N/A}"
+echo "Firewall:          ${SYS_FIREWALL:-unknown}"
+echo "Firewall Version:  ${SYS_FIREWALL_VERSION:-N/A}"
+echo "Firewall Active:   ${SYS_FIREWALL_ACTIVE:-unknown}"
+echo ""
+
+#############################################################################
+# STEP 8: Summary
+#############################################################################
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo "                         SUMMARY"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+
+detection_ok=1
+
+[ -z "$SYS_WEB_SERVER" ] || [ "$SYS_WEB_SERVER" = "unknown" ] && {
+    echo "⚠️  WARNING: Web server not detected"
+    detection_ok=0
+}
+
+[ -z "$SYS_DB_TYPE" ] || [ "$SYS_DB_TYPE" = "none" ] && {
+    echo "⚠️  INFO: No database detected (may be intentional)"
+}
+
+[ -z "$SYS_FIREWALL" ] || [ "$SYS_FIREWALL" = "none" ] && {
+    echo "ℹ️  INFO: No firewall detected (may be intentional on standalone)"
+}
+
+if [ $detection_ok -eq 1 ]; then
+    echo "✓ System detection completed successfully"
+    echo ""
+    echo "All critical components detected."
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo ""