Software Management System Documentation
Overview
The Comserv application includes a comprehensive software management system that provides administrators with tools to monitor, update, and deploy the application. This system is integrated into the Admin controller and provides both web-based interfaces and backend functionality for managing software updates.
Current Features
1. Software Management Status Dashboard
Location: Admin Dashboard (/admin)
Method: get_software_management_status() in Admin.pm
The dashboard provides real-time status information about:
Git Status
- Current branch
- Uncommitted changes detection
- Commits behind origin
- Last commit information
Starman Service Status
- Service active/inactive status
- Service uptime information
- Health monitoring
Deployment Status Summary
- Update requirements
- Local changes detection
- Service health status
Automated Recommendations
- Update notifications when behind origin
- Service restart alerts
- Local changes warnings
- System health confirmations
2. Git Pull Functionality
Endpoint: /admin/git_pull
Method: git_pull() and execute_git_pull() in Admin.pm
Features:
Smart Theme Mappings Handling
- Automatic backup of
theme_mappings.json before pull
- Stashing of local changes to prevent conflicts
- Automatic restoration from backup if conflicts occur
- Conflict detection and resolution
Safety Measures
- Admin role verification
- Confirmation required before execution
- Comprehensive logging of all operations
- Rollback capabilities for theme mappings
Output Reporting
- Detailed git operation output
- Success/failure status reporting
- Warning messages for potential issues
3. Production Deployment System
Endpoint: /admin/production_deploy
Method: production_deploy() and execute_production_deploy() in Admin.pm
Features:
Branch Management
- Support for deploying from any branch
- Current branch detection and switching
- Available branches listing
Backup System
- Optional backup branch creation before deployment
- Timestamped backup branches
- Automatic branch switching and restoration
Deployment Process
- Git fetch and pull operations
- Version tagging support
- Automatic Starman service restart
- Service status verification
Safety and Monitoring
- Pre-deployment status checks
- Comprehensive logging
- Error detection and reporting
- Service health verification
4. Deployment Status Monitoring
Method: get_deployment_status() in Admin.pm
Provides:
- Current branch information
- Current commit hash and message
- Last commit timestamp
- Available branches list
- Repository status summary
5. System Statistics Integration
Method: get_system_stats() in Admin.pm
Software-related statistics:
- Git commit count
- Application version from git tags
- Repository health metrics
- Integration with overall system monitoring
Technical Implementation
Architecture
The software management system follows these architectural principles:
- Separation of Concerns
- Status monitoring methods separate from action methods
- UI logic separated from business logic
- Error handling centralized
- Safety First
- All operations require admin privileges
- Confirmation steps for destructive operations
- Comprehensive backup and rollback mechanisms
- Detailed logging for audit trails
- User Experience
- Clear status indicators on dashboard
- Actionable recommendations
- Detailed operation feedback
- Progressive disclosure of information
Security Model
- Authentication: All endpoints require valid user session
- Authorization: Admin role verification for all operations
- Special Access: Hardcoded access for 'Shanta' user (temporary)
- Audit Trail: Comprehensive logging of all operations
Error Handling
The system implements multiple layers of error handling:
- Try-Catch Blocks: All operations wrapped in try-catch
- Git Operation Validation: Output parsing to detect failures
- Service Status Verification: Post-operation health checks
- User Feedback: Clear error messages and warnings
- Logging: Detailed error logging for debugging
File Management
Special handling for critical configuration files:
- Theme Mappings: Automatic backup and restoration
- Local Changes: Stashing and conflict resolution
- Backup Creation: Timestamped backup files
- Permission Handling: Proper file permissions maintained
Integration Points
Dashboard Integration
The software management system is prominently featured on the admin dashboard:
- Status Section: Real-time system status
- Recommendations: Actionable items for administrators
- Quick Actions: Direct links to management functions
- Visual Indicators: Color-coded status displays
Logging Integration
All operations integrate with the centralized logging system:
- Structured Logging: Consistent log format across operations
- Context Information: File, line, and method information
- Severity Levels: Appropriate log levels for different events
- Audit Trail: Complete operation history
Service Integration
The system integrates with system services:
- Starman Management: Service start/stop/restart operations
- System Commands: Git operations and system status checks
- Permission Management: Sudo operations for service control
Configuration
Required Permissions
The system requires the following permissions:
1. Git Operations
- Read access to git repository
- Write access for pull operations
- Branch creation and switching permissions
2. Service Management
- Sudo access for systemctl operations
- Starman service control permissions
3. File System
- Read/write access to application directory
- Backup file creation permissions
- Log file write permissions
Dependencies
The software management system depends on:
- Git: Version control operations
- Systemctl: Service management
- Perl Modules: File::Copy, File::Slurp, POSIX, Try::Tiny
- System Commands: Available git, sudo, systemctl commands
Usage Guidelines
For Administrators
1. Regular Monitoring
- Check dashboard status regularly
- Review recommendations and act on warnings
- Monitor service health indicators
2. Update Procedures
- Use Production Deploy for major updates
- Use Git Pull for simple code updates
- Always review changes before deployment
3. Safety Practices
- Create backups before major deployments
- Test deployments in development first
- Monitor logs after deployments
For Developers
1. Code Changes
- Ensure all changes are committed before deployment
- Test theme mappings changes carefully
- Document any new configuration requirements
2. Deployment Considerations
- Consider impact on running services
- Plan for potential rollback scenarios
- Coordinate with administrators for major changes
Troubleshooting
Common Issues
1. Git Pull Failures
- Check for uncommitted local changes
- Verify network connectivity to git repository
- Review git repository permissions
2. Service Restart Failures
- Check Starman service configuration
- Verify sudo permissions for service control
- Review system logs for service errors
3. Theme Mappings Conflicts
- System automatically handles most conflicts
- Manual resolution may be needed for complex conflicts
- Backup files are always created for safety
Diagnostic Steps
1. Check System Status
- Review dashboard recommendations
- Check git repository status
- Verify service health
2. Review Logs
- Check application logs for errors
- Review system logs for service issues
- Examine git operation output
3. Verify Permissions
- Confirm admin role assignment
- Check file system permissions
- Verify sudo access for service operations
Future Enhancements
See the Development Plans document for planned improvements to the software management system, including:
- Enhanced error handling and recovery
- Automated backup and rollback capabilities
- Dependency management integration
- Advanced deployment strategies
- Monitoring and alerting improvements
Related Documentation