Linux-Server-Management-Toolkit/CROSS_PLATFORM_PLAN.md

Cross-Platform Launcher Implementation Plan

Executive Summary

Transform the launcher from cPanel-only to fully cross-platform supporting:

• Control Panels: cPanel, Plesk, InterWorx
• Standalone Systems: Debian, Ubuntu, AlmaLinux, Rocky Linux, RHEL, CentOS

Current State Analysis

What Works ✅

1. lib/system-detect.sh - Already detects all platforms correctly
2. lib/domain-discovery.sh - Has unified functions for cPanel/Plesk/InterWorx
3. lib/plesk-helpers.sh - 31 Plesk-specific helper functions ready
4. lib/user-manager.sh - Already has Plesk/InterWorx support for user/database queries
5. lib/common-functions.sh - Platform-agnostic utility functions

What's Broken ❌

1. lib/reference-db.sh - Hardcoded cPanel dependencies in 4 locations:
   • Line 255, 265: Uses /var/cpanel/userdata for domain configs
   • Line 370, 390: Uses /etc/trueuserdomains for domain ownership
2. build_domains_section() - 100% cPanel-specific (parses cPanel userdata files)
3. build_wordpress_section() - Assumes /home/username/ directory structure

Platform-Specific Characteristics

Control Panel Systems

cPanel

• Users: /var/cpanel/users/
• Domains: /etc/userdomains, /etc/trueuserdomains
• Config: /var/cpanel/userdata/{user}/{domain}
• Home: /home/{user}/
• Logs: /var/log/apache2/domlogs/
• Detection: /usr/local/cpanel/version

Plesk

• Users: MySQL query to psa.sys_users
• Domains: plesk bin site --list or MySQL psa.domains
• Config: /var/www/vhosts/{domain}/conf/
• Home: /var/www/vhosts/{domain}/
• Logs: /var/www/vhosts/system/{domain}/logs/
• Detection: /usr/local/psa/version

InterWorx

• Users: /home/interworx/var/
• Domains: ~iworx/bin/listaccounts.pex
• Config: /home/{user}/var/{domain}/
• Home: /chroot/home/{user}/
• Logs: /home/{user}/var/{domain}/logs/
• Detection: /usr/local/interworx/bin/status.pex

Standalone Systems (No Control Panel)

Common Characteristics

• Users: Standard /etc/passwd (UID >= 1000)
• Domains: Detect from:
  • Apache/Nginx vhosts: /etc/apache2/sites-enabled/, /etc/nginx/sites-enabled/
  • /etc/hosts entries
  • DNS records (if available)
• Home: /home/{user}/ or /var/www/
• Logs: /var/log/apache2/, /var/log/nginx/
• Web roots: /var/www/html/, /var/www/{domain}/, /usr/share/nginx/html/

Debian/Ubuntu Specific

• Apache config: /etc/apache2/sites-available/
• Nginx config: /etc/nginx/sites-available/
• Default web root: /var/www/html/
• Package manager: apt

RHEL/AlmaLinux/Rocky/CentOS Specific

• Apache config: /etc/httpd/conf.d/
• Nginx config: /etc/nginx/conf.d/
• Default web root: /var/www/html/ or /usr/share/nginx/html/
• Package manager: dnf or yum

Implementation Strategy

Phase 1: Refactor build_domains_section() 🎯 PRIORITY

Current Issue: Entirely cPanel-specific, parses userdata files

Solution: Create platform-specific domain discovery logic

build_domains_section() {
    echo "[DOMAINS]" >> "$SYSREF_DB"

    case "$SYS_CONTROL_PANEL" in
        cpanel)
            build_domains_cpanel
            ;;
        plesk)
            build_domains_plesk
            ;;
        interworx)
            build_domains_interworx
            ;;
        *)
            build_domains_standalone
            ;;
    esac

    finish_progress
    echo "" >> "$SYSREF_DB"
}

Sub-functions to create:

1. build_domains_cpanel() - Keep existing logic
2. build_domains_plesk() - Use plesk_list_domains + plesk_get_* functions
3. build_domains_interworx() - Use InterWorx CLI tools
4. build_domains_standalone() - Parse Apache/Nginx vhosts

Phase 2: Refactor build_wordpress_section()

Current Issue: Assumes /home/username/ paths, uses cPanel-specific logic

Solution: Use $SYS_USER_HOME_BASE and panel-agnostic path parsing

build_wordpress_section() {
    echo "[WORDPRESS]" >> "$SYSREF_DB"

    # Use panel-agnostic search paths
    case "$SYS_CONTROL_PANEL" in
        cpanel)
            search_paths="/home/*/public_html"
            ;;
        plesk)
            search_paths="/var/www/vhosts/*/httpdocs /var/www/vhosts/*/httpsdocs"
            ;;
        interworx)
            search_paths="/chroot/home/*/var/*/html"
            ;;
        *)
            search_paths="/var/www/*/public_html /var/www/html /home/*/public_html"
            ;;
    esac

    # Find wp-config.php in all search paths
    # Extract domain/owner using get_domain_owner() and path analysis
}

Phase 3: Add Standalone Web Server Detection

New functions needed in system-detect.sh:

detect_vhosts_standalone() {
    # Scan Apache sites-enabled
    if [ -d /etc/apache2/sites-enabled ]; then
        # Parse ServerName/ServerAlias from .conf files
    fi

    # Scan Nginx sites-enabled
    if [ -d /etc/nginx/sites-enabled ]; then
        # Parse server_name from .conf files
    fi

    # Parse /etc/httpd/conf.d/ for RHEL-based
}

Phase 4: Enhance Domain Discovery for Standalone

New helper library: lib/standalone-helpers.sh

Functions needed:

• standalone_list_domains() - Parse vhost configs
• standalone_get_docroot() - Extract DocumentRoot/root directive
• standalone_get_logdir() - Extract log paths from vhost configs
• standalone_get_owner() - Use stat -c "%U" on document root
• standalone_list_users() - Filter /etc/passwd for UID >= 1000

Phase 5: Universal WordPress Detection

Current limitations: Only searches /home/ paths

Enhanced approach:

# Multi-path WordPress scanner
find_wordpress_installations() {
    local search_paths=""

    case "$SYS_CONTROL_PANEL" in
        cpanel) search_paths="/home" ;;
        plesk) search_paths="/var/www/vhosts" ;;
        interworx) search_paths="/chroot/home" ;;
        *)
            # Standalone: check common webroot locations
            search_paths="/var/www /home /usr/share/nginx"
            ;;
    esac

    # Find all wp-config.php files
    find $search_paths -name wp-config.php -type f 2>/dev/null
}

Implementation Phases with Testing

Phase 1: Reference Database Refactor (Week 1)

• Create build_domains_cpanel() (extract existing code)
• Create build_domains_plesk() (use plesk-helpers)
• Create build_domains_interworx() (use interworx-helpers if exists)
• Create build_domains_standalone() (new vhost parser)
• Test on cPanel server (verify no regression)
• Test on Plesk server (verify domain discovery)

Phase 2: WordPress Detection (Week 1)

• Refactor build_wordpress_section() with multi-path search
• Add panel-specific path extraction logic
• Test on cPanel (verify existing WordPress detected)
• Test on Plesk (verify WordPress detected)
• Test on standalone Ubuntu (verify WordPress detected)

Phase 3: Standalone Helpers (Week 2)

• Create lib/standalone-helpers.sh
• Implement vhost parsing (Apache)
• Implement vhost parsing (Nginx)
• Implement user discovery (UID filtering)
• Add exports to domain-discovery.sh
• Test on Debian/Ubuntu with Apache
• Test on AlmaLinux with Nginx

Phase 4: Integration Testing (Week 2)

• Test full launcher on cPanel server
• Test full launcher on Plesk server
• Test full launcher on InterWorx server (if available)
• Test full launcher on Ubuntu standalone
• Test full launcher on AlmaLinux standalone
• Test full launcher on Debian standalone

Phase 5: Documentation (Week 3)

• Update README with platform support matrix
• Document standalone system requirements
• Create troubleshooting guide for each platform
• Add platform-specific installation notes

Database Format Compatibility

The current .sysref format is already platform-agnostic:

DOMAIN|domain|owner|docroot|logdir|access_log|php_version|is_primary|type|aliases|http|https|status

All fields map universally:

• domain - Same on all platforms
• owner - Username from any system
• docroot - Absolute path (any location)
• logdir - Absolute path (any location)
• access_log - Absolute path (any location)
• php_version - Detected version string
• is_primary - yes/no (determined by logic)
• type - primary/addon/alias/subdomain (universal concepts)
• aliases - Space-separated list
• http/https/status - HTTP status codes (universal)

No format changes needed - only the methods to populate these fields change per platform.

Risk Mitigation

Backward Compatibility

• ✅ Keep all existing cPanel code paths functional
• ✅ Use case statements for platform-specific logic
• ✅ Default to cPanel behavior if platform unknown
• ✅ Existing cPanel installations continue working without changes

Testing Strategy

• ✅ Test on live cPanel server FIRST (prevent regressions)
• ✅ Test on Plesk server SECOND (validate new platform)
• ✅ Test on standalone systems THIRD (validate fallback logic)
• ✅ Keep old commits in git history for easy revert

Fallback Mechanisms

• ✅ If vhost parsing fails → scan /var/www for directories
• ✅ If user detection fails → show "unknown" owner
• ✅ If WordPress detection fails → skip silently (don't crash)
• ✅ If domain discovery returns empty → try manual directory scan

Success Criteria

Minimum Viable Product (MVP)

• cPanel: 100% functional (already working)
• Plesk: Domain/user/database discovery working
• Standalone: Basic domain/WordPress detection working

Full Feature Parity

• All platforms detect domains correctly
• All platforms detect WordPress installations
• All platforms show correct ownership
• All platforms display accurate statistics
• All modules work on all platforms (or gracefully skip)

Next Immediate Steps

1. Create standalone-helpers.sh - New helper library for non-panel systems
2. Refactor build_domains_section() - Split into platform-specific functions
3. Test on cPanel - Ensure no regressions
4. Test on Plesk - Validate Plesk domain discovery
5. Document platform support - Update README with compatibility matrix

---

Estimated Timeline: 2-3 weeks for full cross-platform support Priority: High - Blocking Plesk deployment Risk: Medium - Potential for breaking cPanel if not careful Complexity: Medium-High - Requires understanding 4+ different platforms