Linux-Server-Management-Toolkit/DEVELOPMENT-GUIDELINES.md

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
2. Script Design Standards
3. User Experience Guidelines
4. Shared Resources
5. Testing Guidelines
6. 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:

#!/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 /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

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

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

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:

# 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:

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:

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:

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:

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:

# 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

   # Test each user input accepts "0" to cancel
   bash script.sh
   # Enter 0 at each prompt
   # Verify clean exit
   

2. Path Resolution

   # Verify libraries load correctly
   bash -n /path/to/script.sh  # Syntax check
   bash /path/to/script.sh     # Run from anywhere
   

3. Menu Navigation

   # Navigate: Main → Category → Script → Cancel
   bash launcher.sh
   # Select through menus
   # Cancel and verify return to previous menu
   

4. Error Handling

   # 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 <noreply@anthropic.com>

Commit Workflow

# 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

# modules/category/new-script.sh

2. Add to Category Menu

Edit launcher.sh:

# 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

# 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:

# 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.