diff --git a/DEVELOPMENT-GUIDELINES.md b/DEVELOPMENT-GUIDELINES.md new file mode 100644 index 0000000..f466a0e --- /dev/null +++ b/DEVELOPMENT-GUIDELINES.md @@ -0,0 +1,606 @@ +# Server Management Toolkit - Development Guidelines + +**Version:** 2.1.0 +**Last Updated:** 2025-11-07 + +This document provides uniform standards and quick reference for developing and maintaining the Server Management Toolkit. + +--- + +## Table of Contents + +1. [Project Structure & File Map](#project-structure--file-map) +2. [Script Design Standards](#script-design-standards) +3. [User Experience Guidelines](#user-experience-guidelines) +4. [Shared Resources](#shared-resources) +5. [Testing Guidelines](#testing-guidelines) +6. [Git Workflow](#git-workflow) + +--- + +## Project Structure & File Map + +### Directory Layout + +``` +server-toolkit/ +├── launcher.sh # Main entry point - menu system +├── README.md # User documentation +├── DEVELOPMENT-GUIDELINES.md # This file (developer reference) +│ +├── lib/ # Shared libraries (NEVER modify without testing all scripts) +│ ├── common-functions.sh # Core utilities (print_*, press_enter, etc.) +│ ├── system-detect.sh # OS/cPanel detection (SYS_* variables) +│ ├── user-manager.sh # cPanel user functions (select_user_interactive, etc.) +│ ├── mysql-analyzer.sh # Database analysis utilities +│ ├── ip-reputation.sh # Centralized IP reputation tracking +│ └── reference-db.sh # Session-based cross-module intelligence (.sysref) +│ +├── config/ # Configuration files +│ ├── settings.conf # Main configuration +│ ├── whitelist-ips.txt # IP whitelist +│ └── whitelist-user-agents.txt # User-Agent whitelist +│ +├── modules/ # Modular scripts by category +│ ├── security/ # Security & threat analysis +│ │ ├── bot-analyzer.sh +│ │ ├── live-attack-monitor.sh +│ │ ├── enable-cphulk.sh +│ │ └── ip-reputation-manager.sh +│ │ +│ ├── website/ # Website diagnostics +│ │ ├── website-error-analyzer.sh +│ │ ├── 500-error-tracker.sh +│ │ ├── wordpress-menu.sh # WordPress submenu +│ │ └── wordpress/ # WordPress-specific tools +│ │ └── wordpress-cron-manager.sh +│ │ +│ ├── backup/ # Acronis Cyber Protect integration +│ │ ├── acronis-backup-manager.sh +│ │ ├── acronis-trigger-backup.sh +│ │ ├── acronis-agent-status.sh +│ │ └── [14 other acronis scripts] +│ │ +│ ├── diagnostics/ # System diagnostics +│ │ └── system-health-check.sh +│ │ +│ ├── performance/ # Performance analysis +│ │ ├── mysql-query-analyzer.sh +│ │ └── hardware-health-check.sh +│ │ +│ └── maintenance/ # System maintenance +│ └── cleanup-toolkit-data.sh +│ +└── tools/ # Utility scripts + └── diagnostic-report.sh +``` + +### Key File Locations Quick Reference + +| Resource | Path | Purpose | +|----------|------|---------| +| **Main Launcher** | `/root/server-toolkit/launcher.sh` | Menu system entry point | +| **Reference DB** | `/root/server-toolkit/.sysref` | Session-based intelligence sharing | +| **Common Functions** | `/root/server-toolkit/lib/common-functions.sh` | Shared utilities all scripts use | +| **IP Reputation** | `/root/server-toolkit/lib/ip-reputation.sh` | Centralized IP tracking | +| **User Manager** | `/root/server-toolkit/lib/user-manager.sh` | cPanel user selection | +| **Website Errors** | `/root/server-toolkit/modules/website/website-error-analyzer.sh` | Intelligent error analysis | +| **WordPress Cron** | `/root/server-toolkit/modules/website/wordpress/wordpress-cron-manager.sh` | WP cron management | +| **Security Menu** | Search `show_security_menu` in launcher.sh | 3-tier security structure | + +--- + +## Script Design Standards + +### Standard Script Template + +Every module script should follow this structure: + +```bash +#!/bin/bash + +################################################################################ +# Script Name +################################################################################ +# Purpose: Clear description of what this script does +# Features: +# - Feature 1 +# - Feature 2 +# - Feature 3 +################################################################################ + +# Determine correct path to root based on script location +# Example paths: +# modules/security/script.sh → ../../ +# modules/website/script.sh → ../../ +# modules/website/wordpress/script.sh → ../../../ + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +source "$SCRIPT_DIR/lib/common-functions.sh" +source "$SCRIPT_DIR/lib/system-detect.sh" + +# Optional libraries (only include if needed) +# source "$SCRIPT_DIR/lib/user-manager.sh" +# source "$SCRIPT_DIR/lib/ip-reputation.sh" +# source "$SCRIPT_DIR/lib/reference-db.sh" + +# Root check +if [ "$EUID" -ne 0 ]; then + print_error "This script must be run as root" + exit 1 +fi + +# Main script logic starts here +clear +print_banner "Script Name" + +echo "" +# ... script functionality ... +echo "" + +press_enter +``` + +### Path Resolution Rules + +**CRITICAL:** Always verify `SCRIPT_DIR` calculation based on script location: + +| Script Location | Correct SCRIPT_DIR | +|----------------|-------------------| +| `modules/category/script.sh` | `../../` (up 2 levels) | +| `modules/category/subcategory/script.sh` | `../../../` (up 3 levels) | +| `tools/script.sh` | `../` (up 1 level) | + +**Test after moving scripts:** +```bash +bash /path/to/script.sh # Should load libraries without errors +``` + +--- + +## User Experience Guidelines + +### 1. Cancel/Back Options (MANDATORY) + +**Every user input must allow cancellation:** + +#### Menu Options +```bash +echo " 1) Option One" +echo " 2) Option Two" +echo " 3) Option Three" +echo " 0) Cancel and return to menu" # REQUIRED +echo "" +read -p "Select option: " choice + +case $choice in + 0) + echo "" + echo "Operation cancelled." + echo "" + exit 0 + ;; + # ... other options ... +esac +``` + +#### Text Input Prompts +```bash +echo -n "Enter domain name (or 0 to cancel): " +read -r domain + +if [ -z "$domain" ] || [ "$domain" = "0" ]; then + echo "Operation cancelled." + press_enter + exit 0 +fi +``` + +#### Confirmation Prompts +```bash +echo -n "Are you sure? (y/n) [n]: " +read -r confirm + +if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then + echo "Operation cancelled." + press_enter + exit 0 +fi +``` + +### 2. Consistent Messaging + +Use these standard messages: + +```bash +# Success +print_success "Operation completed successfully" + +# Error +print_error "Something went wrong" + +# Warning +print_warning "This action cannot be undone" + +# Info +print_info "Processing data..." + +# Cancellation +echo "Operation cancelled." +``` + +### 3. Always Use press_enter + +**REQUIRED at end of every script:** + +```bash +echo "" +print_success "Task completed" +echo "" +press_enter # Gives user time to read output before returning to menu +``` + +--- + +## Shared Resources + +### 1. Reference Database (.sysref) + +**Session-based intelligence sharing between modules** + +Location: `/root/server-toolkit/.sysref` +Purpose: Share discovered information during a single session +**NOT persistent** - cleared on cleanup + +#### Usage: + +```bash +source "$SCRIPT_DIR/lib/reference-db.sh" + +# Store WordPress installation +db_store_wordpress "domain.com" "username" "/home/user/public_html" "wp_db" "wp_user" "6.4" "15" "3" + +# Retrieve WordPress installations +wp_sites=$(db_get_all_wordpress) +while IFS='|' read -r type domain owner path db_name db_user version plugins themes; do + echo "Found: $domain owned by $owner" +done <<< "$wp_sites" + +# Query specific domain +wp_info=$(db_get_wordpress_by_domain "example.com") +``` + +#### Available Functions: + +| Function | Purpose | +|----------|---------| +| `db_store_wordpress` | Store WP installation details | +| `db_get_all_wordpress` | Get all WP sites | +| `db_get_wordpress_by_domain` | Get specific domain | +| `db_store_user_domain_map` | Map user to domains | +| `db_get_user_domains` | Get user's domains | + +### 2. IP Reputation System + +**Centralized IP tracking across all security modules** + +Location: `/root/server-toolkit/lib/ip-reputation.sh` + +#### Usage: + +```bash +source "$SCRIPT_DIR/lib/ip-reputation.sh" + +# Check if IP is a known bot +if is_known_bot "1.2.3.4"; then + echo "This is a bot" +fi + +# Check if IP should be filtered +if should_filter_ip "1.2.3.4"; then + continue # Skip this IP +fi + +# Log threat detection +log_ip_threat "1.2.3.4" "SSH brute force" "80" + +# Query reputation +rep_score=$(get_ip_reputation "1.2.3.4") +``` + +### 3. User Manager + +**Consistent cPanel user selection** + +Location: `/root/server-toolkit/lib/user-manager.sh` + +#### Usage: + +```bash +source "$SCRIPT_DIR/lib/user-manager.sh" + +# Interactive user selection +select_user_interactive "Select cPanel user to analyze" +if [ -n "$SELECTED_USER" ]; then + echo "Selected: $SELECTED_USER" +else + echo "No user selected" + exit 0 +fi + +# List all users +list_all_users + +# Get user's domains +domains=$(get_user_domains "username") +``` + +### 4. Common Functions + +**Core utilities all scripts use** + +Location: `/root/server-toolkit/lib/common-functions.sh` + +#### Essential Functions: + +```bash +# Output formatting +print_banner "My Script Title" +print_success "Operation completed" +print_error "Failed to complete" +print_warning "Proceed with caution" +print_info "Processing..." + +# User interaction +press_enter # Wait for user before returning to menu + +# Colors (use sparingly, prefer print_* functions) +echo -e "${GREEN}Success${NC}" +echo -e "${RED}Error${NC}" +echo -e "${YELLOW}Warning${NC}" +``` + +--- + +## Testing Guidelines + +### Before Committing + +**ALWAYS test these scenarios:** + +1. **Cancel Functionality** + ```bash + # Test each user input accepts "0" to cancel + bash script.sh + # Enter 0 at each prompt + # Verify clean exit + ``` + +2. **Path Resolution** + ```bash + # Verify libraries load correctly + bash -n /path/to/script.sh # Syntax check + bash /path/to/script.sh # Run from anywhere + ``` + +3. **Menu Navigation** + ```bash + # Navigate: Main → Category → Script → Cancel + bash launcher.sh + # Select through menus + # Cancel and verify return to previous menu + ``` + +4. **Error Handling** + ```bash + # Test with invalid input + # Test with missing files + # Test with permission issues + ``` + +### Test Checklist + +- [ ] Script loads libraries without errors +- [ ] All menus have "0) Cancel" option +- [ ] All text inputs accept "0" to cancel +- [ ] `press_enter` called at end +- [ ] `print_banner` used for title +- [ ] Error messages use `print_error` +- [ ] Success messages use `print_success` +- [ ] Root check present +- [ ] No syntax errors (`bash -n script.sh`) +- [ ] Works when called from launcher +- [ ] Works when called directly + +--- + +## Git Workflow + +### Commit Message Template + +``` +Brief summary of changes (50 chars max) + +Changes: +- Specific change 1 +- Specific change 2 +- Specific change 3 + +[Optional sections:] +User Experience Improvements: +- Improvement 1 +- Improvement 2 + +Technical Details: +- Detail 1 +- Detail 2 + +Tested: +✓ Test scenario 1 +✓ Test scenario 2 +✓ Test scenario 3 + +🤖 Generated with Claude Code +https://claude.com/claude-code + +Co-Authored-By: Claude +``` + +### Commit Workflow + +```bash +# 1. Check status +git status + +# 2. Add all changes +git add -A + +# 3. Commit with descriptive message +git commit -m "$(cat <<'EOF' +Your commit message here +EOF +)" + +# 4. Push to remote +git push origin main +``` + +### What to Commit + +**DO commit:** +- Script files (*.sh) +- Configuration templates +- Documentation (*.md) +- Library updates + +**DON'T commit:** +- `.sysref` (session data) +- `.sysref.timestamp` +- Temporary files (`/tmp/*`) +- User-specific configs with credentials +- Cache files + +### Commit Frequency + +- After completing a feature +- After fixing bugs +- Before major refactoring +- At end of work session + +--- + +## Menu Structure Standards + +### Menu Hierarchy Rules + +1. **Main Menu** → Categories (Security, Website, Performance, etc.) +2. **Category Menu** → Sub-categories or direct scripts +3. **Sub-Menu** → Specific tools or actions +4. **Script** → Actual functionality + +### Adding New Scripts + +#### 1. Create Script in Correct Category + +```bash +# modules/category/new-script.sh +``` + +#### 2. Add to Category Menu + +Edit `launcher.sh`: + +```bash +# Add to show_category_menu function +echo " X) New Script Name - Description" + +# Add to handle_category_menu case statement +case $choice in + X) run_module "category" "new-script.sh" ;; +esac +``` + +#### 3. Update README.md + +Add to feature list and structure documentation + +--- + +## Quick Reference + +### Common Tasks + +| Task | Command/Location | +|------|------------------| +| Test script syntax | `bash -n script.sh` | +| Run specific script | `bash /root/server-toolkit/modules/category/script.sh` | +| Clear session data | Option 8 in main menu | +| View logs | Check `/tmp/` for script outputs | +| Check running shells | `/bashes` command | +| Force library reload | Re-source in script or restart launcher | + +### File Naming Conventions + +- Use kebab-case: `my-script-name.sh` +- Be descriptive: `wordpress-cron-manager.sh` not `wp-cron.sh` +- Match purpose: `enable-cphulk.sh` clearly states what it does + +### Variable Naming + +```bash +# Global constants (UPPERCASE) +APACHE_LOG_DIR="/var/log/apache2" +MAX_RETRIES=3 + +# Local variables (lowercase with underscores) +domain_name="example.com" +error_count=0 + +# Function names (lowercase with underscores) +check_wp_installation() { + # ... +} +``` + +--- + +## Troubleshooting Development Issues + +### Script Can't Find Libraries + +**Problem:** `source: file not found` + +**Solution:** +```bash +# Check SCRIPT_DIR calculation +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +echo "SCRIPT_DIR: $SCRIPT_DIR" + +# Verify from script location: +# modules/category/script.sh → goes up 2 levels +# modules/category/sub/script.sh → goes up 3 levels +``` + +### Menu Option Not Working + +**Problem:** Script doesn't launch from menu + +**Solution:** +1. Check `run_module` call in launcher.sh uses correct category and filename +2. Verify script is executable: `chmod +x script.sh` +3. Check script has `#!/bin/bash` shebang + +### Cancel Not Working + +**Problem:** User can't exit from prompt + +**Solution:** +1. Add `0) Cancel` to all menus +2. Add `(or 0 to cancel)` to all text prompts +3. Check for empty or "0" input and exit cleanly + +--- + +**Remember:** Consistency is key. Follow these guidelines for every new script and update existing scripts to match these standards as you work on them. + +**When in doubt:** Look at `modules/website/wordpress/wordpress-cron-manager.sh` as a reference implementation that follows all standards.