Code Review: plex-setup.sh (Post-1.0 Improvement Plan)¶
History. A point-in-time review of app-setup/plex-setup.sh from 2025-09-12. It was not carried out as a plan: its main refactor did not happen, and main() is still one function of about 300 lines. The line numbers and some function names below are out of date. For example, the SMB mount it reviews is now an NFS mount (setup_persistent_nfs_mount). For the current script see Plex.
Date: 2025-09-12
Script: app-setup/plex-setup.sh
Lines of Code: 1,654
Review Type: Post-1.0 Maintenance & Improvement Assessment
Executive Summary¶
The plex-setup.sh script is a functionally robust and feature-complete solution for Plex Media Server deployment with migration capabilities. While it demonstrates excellent security practices and comprehensive error handling, it shows clear signs of iterative development that have resulted in structural complexity impacting long-term maintainability.
Overall Assessment: B+ (Good functionality, needs structural improvement)
Strengths¶
✅ Security & Best Practices¶
- Exceptional credential handling: Keychain integration, memory cleanup, masked logging
- Proper privilege escalation: Contextual sudo prompts with descriptive messages
- Input validation: Command line arguments, port numbers, hostnames
- Safe database operations: Backups, integrity checks, transaction-like behavior
- File permissions: Correct ownership and permissions for multi-user access
- Zero shellcheck issues: Perfect compliance with shell scripting standards
✅ Error Handling & Logging¶
- Comprehensive error collection: Immediate display with end-of-run summary
- Graceful degradation: Continues operation when non-critical components fail
- Detailed context tracking: Line numbers, section identification, script context
- User-friendly diagnostics: Clear troubleshooting suggestions and guidance
✅ Feature Completeness¶
- Migration capabilities: Both local and remote with SSH connectivity testing
- Port conflict resolution: Automatic detection and custom port configuration
- Multi-user support: Per-user LaunchAgents and shared configurations
- Network discovery: Automatic scanning for existing Plex servers
- Database path updates: Comprehensive SQLite operations for migration
Critical Issues Requiring Improvement¶
🔴 HIGH PRIORITY: Function Organization & Size¶
Problem: Violation of single responsibility principle with overly large functions.
Specific Issues:
main(): 287 lines (lines 1355-1641) - handles multiple distinct phasessetup_persistent_smb_mount(): 171 lines (lines 376-546) - complex nested logicmigrate_plex_from_host(): 98 lines (lines 783-881) - multiple concerns mixedupdate_migrated_library_paths(): 147 lines (lines 1031-1177) - complex database operations
Impact:
- Difficult to test individual features in isolation
- Hard to debug specific functionality
- Maintenance requires understanding entire large functions
- Code reuse is limited
Recommended Refactoring:
# Current main() should be broken into logical phases:
main() {
setup_prerequisites
handle_migration_setup
perform_installation
apply_configuration
display_completion_summary
}
# Extract nested functionality:
setup_persistent_smb_mount() {
validate_mount_safety
retrieve_nas_credentials
configure_mount_script
deploy_user_mounts
test_immediate_mount
}
🟡 MEDIUM PRIORITY: Complex Conditional Logic¶
Problem: Deeply nested conditionals make logic flow hard to follow.
Specific Issues:
- Migration decision logic: 130 lines of nested conditions (lines 1371-1501)
- Port configuration: 3 different code paths with inconsistent patterns
- Flag validation: Could be simplified with better structure
Current Problematic Pattern:
# Lines 1371-1501: Complex nested migration logic
if [[ "${SKIP_MIGRATION}" != "true" && -z "${MIGRATE_FROM}" ]]; then
if [[ "${MIGRATE}" == "true" ]] || confirm "Do you want to migrate..."; then
# 100+ lines of deeply nested logic with multiple branches
if [[ -n "${discovered_servers}" ]]; then
# Another 50+ lines of server selection logic
fi
fi
fi
Recommended Strategy Pattern:
determine_migration_strategy() {
if [[ "${SKIP_MIGRATION}" == "true" ]]; then
echo "skip"
elif [[ -n "${MIGRATE_FROM}" ]]; then
echo "remote:${MIGRATE_FROM}"
elif [[ "${MIGRATE}" == "true" ]] || confirm "Migrate from existing server?" "n"; then
echo "interactive"
else
echo "fresh"
fi
}
# Usage in main():
case "$(determine_migration_strategy)" in
"skip") log "Starting fresh installation" ;;
"remote:"*) migrate_from_remote "${strategy#remote:}" ;;
"interactive") handle_interactive_migration ;;
"fresh") setup_fresh_installation ;;
esac
🟡 MEDIUM PRIORITY: Variable Scope & Management¶
Problem: Global variable modification within nested functions creates hidden dependencies.
Specific Issues:
- Line 697:
MIGRATE_FROM="${local_hostname}"- global modification intest_ssh_connection() - Line 807:
TARGET_PLEX_PORT=$((SOURCE_PLEX_PORT + 1))- global assignment in migration function - Sensitive variables persist longer than necessary in memory
- Missing
localdeclarations in some functions
Impact:
- Functions have hidden side effects
- Difficult to reason about variable state
- Potential security implications for credential variables
Recommended Approach:
# Return values instead of modifying globals:
resolve_hostname() {
local host="$1"
# Resolution logic here
echo "${resolved_hostname}" # Return via stdout
}
# Usage:
MIGRATE_FROM=$(resolve_hostname "${MIGRATE_FROM}")
🟡 MEDIUM PRIORITY: Code Duplication¶
Problem: Similar patterns repeated throughout the script.
Specific Examples:
- plist Validation Pattern (lines 508, 1302):
if sudo -iu "${target_user}" plutil -lint "${plist_file}"; then
log "plist syntax validated"
else
collect_error "Invalid plist syntax"
fi
- SSH Connection Testing - Similar logic in multiple functions
- Port Validation - Repeated in 3 different locations with slight variations
Recommended Utilities:
validate_plist() {
local plist_file="$1"
local user="${2:-${USER}}"
if sudo -iu "${user}" plutil -lint "${plist_file}" >/dev/null 2>&1; then
log "✅ plist syntax validated: $(basename "${plist_file}")"
return 0
else
collect_error "Invalid plist syntax: ${plist_file}"
return 1
fi
}
validate_port() {
local port="$1"
if [[ "${port}" =~ ^[0-9]+$ && "${port}" -gt 1024 && "${port}" -lt 65536 ]]; then
return 0
fi
return 1
}
Minor Issues¶
🟢 LOW PRIORITY: Magic Numbers & Hardcoded Values¶
Issues:
- Port ranges hardcoded:
1024,65536 - Timeout values scattered:
3,5,10seconds - Path patterns repeated:
Media/,.local/mnt/
Recommendation: Define constants section:
# Configuration constants
readonly MIN_PORT=1025
readonly MAX_PORT=65535
readonly SSH_TIMEOUT=10
readonly DNS_DISCOVERY_TIMEOUT=3
readonly MEDIA_PATH_PATTERN="Media/"
readonly MOUNT_BASE=".local/mnt"
Architectural Improvement Proposals¶
1. Phase-Based Execution Model¶
Replace monolithic main() with clear execution phases:
readonly SETUP_PHASES=(
"validate_prerequisites"
"determine_migration_strategy"
"setup_storage_mounts"
"install_plex_application"
"apply_configuration"
"configure_autostart"
"display_completion_info"
)
main() {
for phase in "${SETUP_PHASES[@]}"; do
set_section "Phase: ${phase//_/ }"
if ! execute_phase "${phase}"; then
collect_error "Failed in phase: ${phase}"
exit 1
fi
done
}
2. Migration Strategy Abstraction¶
# Migration strategies as separate functions:
migration_strategy_skip() { log "Fresh installation selected"; }
migration_strategy_remote() { migrate_from_remote "$1"; }
migration_strategy_local() { apply_local_migration; }
migration_strategy_interactive() { handle_interactive_migration; }
# Clean dispatch:
execute_migration_strategy() {
local strategy
strategy=$(determine_migration_strategy)
"migration_strategy_${strategy%%:*}" "${strategy#*:}"
}
3. Configuration Builder Pattern¶
Centralize configuration decisions:
build_plex_configuration() {
local -a config_options=()
[[ -n "${TARGET_PLEX_PORT:-}" ]] && config_options+=("--port=${TARGET_PLEX_PORT}")
[[ -n "${PLEX_SERVER_NAME:-}" ]] && config_options+=("--name=${PLEX_SERVER_NAME}")
[[ "${MIGRATE_FROM:-}" ]] && config_options+=("--migrated-from=${MIGRATE_FROM}")
printf '%s\n' "${config_options[@]}"
}
Database Operations Improvement¶
The update_migrated_library_paths() function handles complex SQLite operations and could benefit from:
- Extraction into separate module:
plex-database-utils.sh - Transaction-based operations: Ensure atomicity
- Better error recovery: More granular rollback capabilities
# Proposed structure:
update_library_paths() {
local db_path="$1" old_mount="$2" new_mount="$3"
begin_database_transaction "${db_path}"
update_section_locations "${db_path}" "${old_mount}" "${new_mount}"
update_media_parts "${db_path}" "${old_mount}" "${new_mount}"
update_media_streams "${db_path}" "${old_mount}" "${new_mount}"
commit_database_transaction "${db_path}"
}
Testing Strategy for Refactoring¶
Given the complexity, create focused test scripts before refactoring:
Unit Test Scripts (in /tmp/)¶
# /tmp/test-migration-strategy-logic.sh
# Test migration decision flow with various flag combinations
# /tmp/test-port-configuration.sh
# Test port assignment and validation logic
# /tmp/test-database-path-updates.sh
# Test SQLite operations with mock database
# /tmp/test-ssh-hostname-resolution.sh
# Test hostname resolution and SSH connectivity
# /tmp/test-credential-handling.sh
# Test keychain operations and credential cleanup
Refactoring Implementation Plan¶
Phase 1: Function Decomposition (2-3 days)¶
Priority: HIGH - Addresses maintainability issues
- Extract
main()into 6-7 smaller functions (max 50 lines each) - Break down
setup_persistent_smb_mount()into logical components - Split migration logic into separate functions per strategy
- Extract database operations into dedicated functions
Success Criteria:
- No function longer than 75 lines
- Each function has single, clear responsibility
- All existing functionality preserved
- Zero shellcheck issues maintained
Phase 2: Logic Simplification (1-2 days)¶
Priority: MEDIUM - Improves readability and debugging
- Implement migration strategy pattern
- Centralize port configuration logic
- Extract and deduplicate common patterns
- Improve variable scoping
Success Criteria:
- Conditional nesting depth reduced by 50%
- No global variable modifications in nested functions
- Common patterns extracted into utilities
Phase 3: Code Organization (1 day)¶
Priority: LOW - Polish and maintainability
- Group related functions together
- Add comprehensive function documentation
- Define constants section
- Improve naming consistency
Success Criteria:
- Functions logically organized
- All magic numbers defined as constants
- Comprehensive inline documentation
Quality Metrics Goals¶
Current State:
- Lines of Code: 1,654
- Longest Function: 287 lines (
main()) - Shellcheck Issues: 0 ✅
- Cyclomatic Complexity: High
Target State (Post-1.0):
- Lines of Code: <1,200 (25% reduction through deduplication)
- Longest Function: <75 lines
- Shellcheck Issues: 0 (maintained)
- Cyclomatic Complexity: Medium
- Function Count: ~35-40 (increased modularity)
Risk Assessment¶
Low Risk Refactoring:
- Function extraction (preserves all logic)
- Variable scoping improvements
- Code deduplication
- Documentation additions
Medium Risk Changes:
- Migration strategy pattern implementation
- Database operation restructuring
- Configuration builder pattern
Mitigation Strategy:
- Create comprehensive test suite before refactoring
- Refactor incrementally with git commits at each stable state
- Test each phase thoroughly before proceeding
- Maintain functional equivalence throughout process
Conclusion¶
The plex-setup.sh script represents excellent functional programming with room for significant structural improvement. The security practices, error handling, and feature completeness should be preserved while addressing the maintainability concerns identified in this review.
The recommended refactoring plan will result in a more maintainable, testable, and extensible codebase while preserving all existing functionality. This investment in code quality will pay dividends for future feature additions and maintenance efforts.
Estimated Effort: 4-6 days of focused development work
Risk Level: Low (functionality preservation, incremental approach)
Business Value: High (improved maintainability, easier debugging, enhanced testability)