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

```bash
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

```bash
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**:

```bash
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**:
```bash
# 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)
- [x] 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