|
| 1 | +# EventPi AutoUpdater Host - Requirements |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +EventPi AutoUpdater Host is a web-based application management system that provides automated deployment and version management for Docker Compose applications. It bridges Git repository version control with containerized application deployment, offering a modern web interface for monitoring and controlling updates across multiple applications. |
| 6 | + |
| 7 | +## Core Functionality |
| 8 | + |
| 9 | +### 1. Git-Based Version Management |
| 10 | + |
| 11 | +#### 1.1 Repository Integration |
| 12 | +- **Git Repository Monitoring**: Track multiple Git repositories containing Docker Compose applications |
| 13 | +- **Automatic Cloning**: Clone repositories on first access if not locally available |
| 14 | +- **Remote Synchronization**: Fetch latest changes and tags from remote repositories |
| 15 | +- **Tag-Based Versioning**: Use Git tags as version identifiers following semantic versioning (e.g., v1.2.3, ver2.1.0) |
| 16 | + |
| 17 | +#### 1.2 Version Detection and Comparison |
| 18 | +- **Current Version Tracking**: Maintain deployment state with version information in `deployment.state.json` |
| 19 | +- **Available Version Discovery**: Enumerate Git tags to identify available versions |
| 20 | +- **Upgrade Detection**: Compare current deployed version against available tags to identify upgrades |
| 21 | +- **Semantic Version Parsing**: Parse version strings from Git tags (supports v1.2.3, ver1.2.3 formats) |
| 22 | + |
| 23 | +### 2. Docker Compose Management |
| 24 | + |
| 25 | +#### 2.1 Container Orchestration |
| 26 | +- **Docker Compose File Support**: Handle single or multiple docker-compose.yml files per project |
| 27 | +- **Remote Execution**: Execute Docker Compose commands on remote hosts via SSH |
| 28 | +- **Volume Mapping Analysis**: Analyze container volume mappings to translate paths between container and host |
| 29 | +- **Service Lifecycle Management**: Stop, update, and restart Docker Compose services |
| 30 | + |
| 31 | +#### 2.2 Docker Registry Integration |
| 32 | +- **Private Registry Support**: Authenticate with private Docker registries using PAT tokens |
| 33 | +- **Multi-Registry Support**: Handle authentication for multiple registries simultaneously |
| 34 | +- **Docker Hub Integration**: Built-in support for Docker Hub authentication |
| 35 | + |
| 36 | +### 3. Web-Based User Interface |
| 37 | + |
| 38 | +#### 3.1 Dashboard Features |
| 39 | +- **Package Overview**: Display all configured packages with current versions |
| 40 | +- **Update Status Indicators**: Show which packages have available upgrades |
| 41 | +- **Real-time Updates**: Live UI updates using Blazor Server's SignalR connection |
| 42 | +- **Modern UI Framework**: Built with MudBlazor Material Design components |
| 43 | + |
| 44 | +#### 3.2 User Interactions |
| 45 | +- **Individual Package Management**: View details for each configured package |
| 46 | +- **Bulk Operations**: "Update All" functionality to upgrade all packages simultaneously |
| 47 | +- **Update Confirmation**: Clear indication of available upgrades before proceeding |
| 48 | + |
| 49 | +### 4. Network Management Integration |
| 50 | + |
| 51 | +#### 4.1 VPN Control |
| 52 | +- **WireGuard Integration**: Control WireGuard VPN connections (specifically wg0 interface) |
| 53 | +- **NetworkManager Interface**: Use D-Bus communication with NetworkManager for network control |
| 54 | +- **Connection Status Monitoring**: Real-time VPN connection status display |
| 55 | +- **Toggle Control**: Simple on/off switch for VPN connectivity |
| 56 | + |
| 57 | +## Technical Architecture |
| 58 | + |
| 59 | +### 5. Application Stack |
| 60 | + |
| 61 | +#### 5.1 Frontend |
| 62 | +- **Framework**: ASP.NET Core Blazor Server (.NET 9.0) |
| 63 | +- **UI Library**: MudBlazor for Material Design components |
| 64 | +- **Real-time Communication**: SignalR for live updates |
| 65 | +- **Observable Pattern**: ModelingEvolution.Observable for reactive UI updates |
| 66 | + |
| 67 | +#### 5.2 Backend Services |
| 68 | +- **Git Operations**: LibGit2Sharp for repository management |
| 69 | +- **SSH Communication**: SSH.NET for remote command execution |
| 70 | +- **Docker Integration**: Docker.DotNet and Ductus.FluentDocker for container management |
| 71 | +- **Process Execution**: CliWrap for command-line operations |
| 72 | + |
| 73 | +#### 5.3 Configuration Management |
| 74 | +- **JSON Configuration**: appsettings.json with hot-reload support |
| 75 | +- **Environment Variables**: Support for environment-based configuration |
| 76 | +- **File-based Overrides**: Support for external configuration files |
| 77 | + |
| 78 | +### 6. Deployment Architecture |
| 79 | + |
| 80 | +#### 6.1 Containerization |
| 81 | +- **Docker Container**: Runs as a containerized application |
| 82 | +- **Multi-stage Build**: Optimized Dockerfile with development and production stages |
| 83 | +- **Volume Mounting**: `/data` volume for persistent configuration and repositories |
| 84 | +- **Docker Socket Access**: Requires access to host Docker daemon |
| 85 | + |
| 86 | +#### 6.2 Host Communication |
| 87 | +- **SSH Protocol**: Secure communication with Docker host |
| 88 | +- **Network Discovery**: Automatic detection of Docker bridge gateway (172.17.0.1) |
| 89 | +- **Path Translation**: Convert container paths to host paths using volume mappings |
| 90 | + |
| 91 | +## Configuration Schema |
| 92 | + |
| 93 | +### 7. Package Configuration |
| 94 | + |
| 95 | +#### 7.1 Standard Package Format |
| 96 | +```json |
| 97 | +{ |
| 98 | + "RepositoryLocation": "/data/repos/app-name", |
| 99 | + "RepositoryUrl": "https://github.com/user/repository.git", |
| 100 | + "DockerComposeDirectory": "./docker", |
| 101 | + "MergerName": "deployment-user", |
| 102 | + "MergerEmail": "admin@example.com", |
| 103 | + "DockerIoAuth": "base64-encoded-credentials" |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +#### 7.2 Configuration Sections |
| 108 | +- **StdPackages**: Standard package configurations |
| 109 | +- **Packages**: Additional package configurations |
| 110 | +- **SSH Credentials**: `SshUser` and `SshPwd` for host communication |
| 111 | +- **Docker Authentication**: Registry credentials for private repositories |
| 112 | + |
| 113 | +### 8. Security Requirements |
| 114 | + |
| 115 | +#### 8.1 Authentication & Authorization |
| 116 | +- **SSH Key/Password Authentication**: Secure connection to Docker host |
| 117 | +- **Docker Registry Authentication**: Support for private registry access |
| 118 | +- **Volume Security**: Secure handling of mounted volumes and file permissions |
| 119 | + |
| 120 | +#### 8.2 Network Security |
| 121 | +- **TLS/SSL Support**: HTTPS communication capability |
| 122 | +- **VPN Integration**: Secure network connectivity through WireGuard |
| 123 | +- **Container Isolation**: Proper container security boundaries |
| 124 | + |
| 125 | +## Operational Requirements |
| 126 | + |
| 127 | +### 9. Monitoring and Logging |
| 128 | + |
| 129 | +#### 9.1 Application Logging |
| 130 | +- **Structured Logging**: Comprehensive logging using Microsoft.Extensions.Logging |
| 131 | +- **SSH Operation Logging**: Log all remote commands and results |
| 132 | +- **Update Process Tracking**: Log deployment operations and results |
| 133 | +- **Error Handling**: Comprehensive error logging and reporting |
| 134 | + |
| 135 | +#### 9.2 Health Monitoring |
| 136 | +- **Service Health Checks**: Monitor application and dependent service health |
| 137 | +- **Docker Connectivity**: Verify Docker daemon connectivity |
| 138 | +- **SSH Connectivity**: Monitor SSH connection status |
| 139 | +- **Repository Accessibility**: Verify Git repository access |
| 140 | + |
| 141 | +### 10. Performance Requirements |
| 142 | + |
| 143 | +#### 10.1 Scalability |
| 144 | +- **Multiple Package Support**: Handle dozens of packages efficiently |
| 145 | +- **Concurrent Operations**: Support simultaneous package updates |
| 146 | +- **Resource Management**: Efficient memory and CPU usage |
| 147 | +- **Network Optimization**: Minimize bandwidth usage for Git operations |
| 148 | + |
| 149 | +#### 10.2 Reliability |
| 150 | +- **Update Rollback**: Ability to rollback failed deployments |
| 151 | +- **State Persistence**: Maintain deployment state across application restarts |
| 152 | +- **Error Recovery**: Graceful handling of network and deployment failures |
| 153 | +- **Transaction Safety**: Ensure atomic deployment operations |
| 154 | + |
| 155 | +## Integration Requirements |
| 156 | + |
| 157 | +### 11. External System Integration |
| 158 | + |
| 159 | +#### 11.1 Git Providers |
| 160 | +- **GitHub Support**: Full compatibility with GitHub repositories |
| 161 | +- **GitLab Support**: Support for GitLab hosted repositories |
| 162 | +- **Private Git Servers**: Compatible with self-hosted Git solutions |
| 163 | +- **Authentication Methods**: Support for HTTPS and SSH Git authentication |
| 164 | + |
| 165 | +#### 11.2 Container Registries |
| 166 | +- **Docker Hub**: Native support for Docker Hub |
| 167 | +- **Private Registries**: Support for enterprise container registries |
| 168 | +- **Multi-Registry**: Simultaneous support for multiple registries |
| 169 | +- **Authentication**: Token-based and credential-based authentication |
| 170 | + |
| 171 | +### 12. Notification and Alerting |
| 172 | + |
| 173 | +#### 12.1 Update Notifications |
| 174 | +- **Available Update Alerts**: Notify when new versions are available |
| 175 | +- **Deployment Status**: Report success/failure of deployment operations |
| 176 | +- **Error Notifications**: Alert on deployment or connectivity errors |
| 177 | + |
| 178 | +#### 12.2 Communication Channels |
| 179 | +- **Web Interface**: Real-time notifications in the web UI |
| 180 | +- **Email Integration**: Email notifications for critical events |
| 181 | +- **Webhook Support**: Extensible webhook system for external integrations |
| 182 | + |
| 183 | +## Non-Functional Requirements |
| 184 | + |
| 185 | +### 13. Usability |
| 186 | +- **Intuitive Interface**: Simple, clear web interface requiring minimal training |
| 187 | +- **Responsive Design**: Compatible with desktop and mobile browsers |
| 188 | +- **Accessibility**: WCAG compliant interface design |
| 189 | +- **Documentation**: Comprehensive user and administrator documentation |
| 190 | + |
| 191 | +### 14. Maintainability |
| 192 | +- **Modular Architecture**: Clean separation of concerns |
| 193 | +- **Configuration Management**: Externalized configuration |
| 194 | +- **Update Mechanism**: Self-update capability for the AutoUpdater itself |
| 195 | +- **Diagnostic Tools**: Built-in diagnostic and troubleshooting features |
| 196 | + |
| 197 | +### 15. Compatibility |
| 198 | +- **Operating System**: Linux host support (primary target) |
| 199 | +- **Docker Version**: Compatible with Docker 20.10+ and Docker Compose v2 |
| 200 | +- **Browser Support**: Modern browser compatibility (Chrome, Firefox, Safari, Edge) |
| 201 | +- **Network Protocols**: IPv4/IPv6 support |
| 202 | + |
| 203 | +## Future Enhancements |
| 204 | + |
| 205 | +### 16. Planned Features |
| 206 | +- **Role-Based Access Control**: Multi-user support with permissions |
| 207 | +- **API Interface**: RESTful API for programmatic access |
| 208 | +- **Backup Integration**: Automated backup before deployments |
| 209 | +- **Advanced Scheduling**: Cron-based update scheduling |
| 210 | +- **Multi-Host Management**: Manage containers across multiple Docker hosts |
| 211 | +- **Kubernetes Support**: Extend support to Kubernetes deployments |
| 212 | +- **Advanced Notifications**: Slack, Discord, and other notification channels |
| 213 | +- **Deployment Pipelines**: Multi-stage deployment workflows |
| 214 | +- **Health Check Integration**: Application-specific health monitoring |
| 215 | +- **Metrics and Analytics**: Deployment metrics and performance analytics |
0 commit comments