Refactor Windows deployment scripts: unify build and management tools

Major improvements to deployment workflow with unified scripts and interactive menus. New unified scripts: - Build-ROA2WEB.ps1: Interactive menu for building all components * Isolated temp directory for frontend builds (prevents WSL node_modules corruption) * Automatic devDependencies installation (fixes Vite not found issue) * Auto-cleanup after build * Supports both interactive menu and non-interactive CLI - ROA2WEB-Console.ps1: All-in-one deployment and management console * Interactive menus for deploy, manage services, and status checks * Automatic backups before deployment * Smart dependency updates (only if requirements.txt changed) * Health checks after service operations * Color-coded status output * Both interactive and non-interactive modes Removed deprecated scripts (replaced by unified tools): - Build-Frontend.ps1 → Use Build-ROA2WEB.ps1 -Component Frontend - Build-TelegramBot.ps1 → Use Build-ROA2WEB.ps1 -Component TelegramBot - Deploy-ROA2WEB.ps1 → Use ROA2WEB-Console.ps1 [Deploy menu] - Deploy-TelegramBot.ps1 → Use ROA2WEB-Console.ps1 [Deploy menu] - Manage-ROA2WEB.ps1 → Use ROA2WEB-Console.ps1 [Manage menu] Updated documentation: - Complete rewrite of scripts/README.md - Clear workflow guides for first-time deployment and updates - Comparison table v1.0 vs v2.0 - Updated best practices and troubleshooting Benefits: ✅ Reduced from 13 to 8 scripts (better maintainability) ✅ Interactive menus for better UX ✅ Fixed WSL node_modules corruption issue ✅ Smart dependency management (faster deployments) ✅ Unified interface reduces learning curve ✅ Better error handling and health checks 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-12 01:35:14 +02:00
parent a227a10ca8
commit 1832684aca
8 changed files with 1447 additions and 3305 deletions
--- a/deployment/windows/scripts/README.md
+++ b/deployment/windows/scripts/README.md
@@ -4,49 +4,110 @@ Complete reference for ROA2WEB Windows deployment PowerShell scripts (v2.0 - Uni

 ## 📋 Script Overview

-### 🔨 Build Scripts
+### ⭐ Unified Scripts (Recommended)

-#### **Build-ROA2WEB.ps1** ⭐ (UNIFIED - Recommended)
-**Purpose**: Unified build script for all components
+#### **Build-ROA2WEB.ps1** - Unified Build System
+**Purpose**: Build deployment packages for all components with interactive menu

 **Usage**:
 ```powershell
-# Build complete package (default)
+# Interactive mode - shows menu
 .\Build-ROA2WEB.ps1

-# Build specific components
+# Non-interactive mode - specific component
+.\Build-ROA2WEB.ps1 -Component All           # Complete package
 .\Build-ROA2WEB.ps1 -Component Frontend      # Frontend + Backend
 .\Build-ROA2WEB.ps1 -Component Backend       # Backend only
 .\Build-ROA2WEB.ps1 -Component TelegramBot   # Telegram Bot only

 # Custom output path
-.\Build-ROA2WEB.ps1 -OutputPath "D:\builds\roa2web-$(Get-Date -Format 'yyyyMMdd')"
+.\Build-ROA2WEB.ps1 -Component All -OutputPath "D:\builds\roa2web-$(Get-Date -Format 'yyyyMMdd')"
+```
+
+**Interactive Menu**:
+```
+[1] All Components (Frontend + Backend + Telegram Bot)
+[2] Frontend + Backend (Vue.js build + FastAPI backend)
+[3] Backend Only (FastAPI backend + shared modules)
+[4] Telegram Bot Only (Standalone package)
+[Q] Quit
 ```

 **Parameters**:
- `-Component` All|Frontend|Backend|TelegramBot (default: All)
+- `-Component` All|Frontend|Backend|TelegramBot (optional - shows menu if not specified)
 - `-OutputPath` (default: `./deploy-package`)
 - `-Clean` $true|$false (default: $true)

+**Features**:
+- ✅ Interactive menu for component selection
+- ✅ Isolated temp directory for frontend builds (doesn't corrupt WSL node_modules)
+- ✅ Automatic dependency installation (including devDependencies)
+- ✅ Auto-cleanup after build
+- ✅ Generates deployment README
+
 **Output**: Creates `deploy-package/` with complete deployment files

 ---

-#### Build-Frontend.ps1 ⚠️ DEPRECATED
-**Status**: Deprecated in favor of `Build-ROA2WEB.ps1 -Component Frontend`
+#### **ROA2WEB-Console.ps1** - Unified Deployment & Management Console
+**Purpose**: All-in-one console for deploying and managing ROA2WEB services

-Use: `.\Build-ROA2WEB.ps1 -Component Frontend` instead
+**Usage**:
+```powershell
+# Interactive mode - shows main menu
+.\ROA2WEB-Console.ps1
+
+# Non-interactive mode - specific actions
+.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
+.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployBackend
+.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployTelegramBot
+.\ROA2WEB-Console.ps1 -NonInteractive -Action StartAll
+.\ROA2WEB-Console.ps1 -NonInteractive -Action StopAll
+.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartAll
+.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
+```
+
+**Interactive Main Menu**:
+```
+[1] Deploy Components
+    - Deploy Backend + Frontend
+    - Deploy Telegram Bot
+    - Deploy All Components
+
+[2] Manage Services
+    - Start/Stop/Restart All
+    - Start/Stop/Restart Backend
+    - Start/Stop/Restart Telegram Bot
+
+[3] Check Status
+    - Service status
+    - Health checks
+
+[Q] Quit
+```
+
+**Parameters**:
+- `-NonInteractive` Switch to enable non-interactive mode
+- `-Action` DeployBackend|DeployTelegramBot|DeployAll|StartAll|StopAll|RestartAll|Status
+
+**Features**:
+- ✅ Unified interface for deploy + management
+- ✅ Interactive menus with easy navigation
+- ✅ Automatic backups before deployment
+- ✅ Smart dependency updates (only if requirements.txt changed)
+- ✅ Health checks after operations
+- ✅ Color-coded status output
+- ✅ Both interactive and non-interactive modes
+- ✅ Preserves .env configuration files
+
+**Replaces**:
+- ❌ `Deploy-ROA2WEB.ps1` (removed)
+- ❌ `Deploy-TelegramBot.ps1` (removed)
+- ❌ `Manage-ROA2WEB.ps1` (removed)

 ---

-#### Build-TelegramBot.ps1 ⚠️ DEPRECATED
-**Status**: Deprecated in favor of `Build-ROA2WEB.ps1 -Component TelegramBot`
-
-Use: `.\Build-ROA2WEB.ps1 -Component TelegramBot` instead
-
---
-
-### 🚀 Installation Scripts
+### 🚀 Installation Scripts (First-Time Setup)

 #### **Install-ROA2WEB.ps1**
 **Purpose**: First-time installation of Backend + Frontend
@@ -103,140 +164,6 @@ Use: `.\Build-ROA2WEB.ps1 -Component TelegramBot` instead

 ---

-### 📦 Deployment Scripts
-
-#### **Deploy-ROA2WEB.ps1**
-**Purpose**: Deploy updates to existing Backend + Frontend
-
-**Usage**:
-```powershell
-# Auto-detects source path (if run from deploy-package/scripts/)
-.\Deploy-ROA2WEB.ps1
-
-# Explicit source path
-.\Deploy-ROA2WEB.ps1 -SourcePath "C:\Deploy\roa2web-v2"
-
-# Disable automatic restart
-.\Deploy-ROA2WEB.ps1 -RestartService $false
-```
-
-**What it does**:
-1. Creates backup of current deployment
-2. Stops backend service
-3. Updates backend & frontend files (preserves .env)
-4. Checks requirements.txt - updates dependencies if changed
-5. Restarts backend service
-6. Tests health endpoint
-7. Cleans old backups (keeps last 10)
-
-**Parameters**:
- `-InstallPath` (default: `C:\inetpub\wwwroot\roa2web`)
- `-SourcePath` (auto-detected from script location)
- `-BackupEnabled`, `-RestartService`, `-UpdateBackend`, `-UpdateFrontend`
- `-ForceInstallDependencies`
-
---
-
-#### **Deploy-TelegramBot.ps1**
-**Purpose**: Deploy updates to existing Telegram Bot
-
-**Usage**:
-```powershell
-# Auto-detects source path
-.\Deploy-TelegramBot.ps1
-
-# With automatic rollback on failure
-.\Deploy-TelegramBot.ps1 -RollbackOnFailure $true
-```
-
-**What it does**:
-1. Creates backup (app/, requirements.txt, .env, database)
-2. Stops bot service
-3. Removes old app/ directory
-4. Copies new app/ files
-5. Checks requirements.txt - updates dependencies if changed
-6. Preserves .env (never overwrites)
-7. Updates management scripts
-8. Restarts service
-9. Tests health endpoint
-10. **Automatic rollback** on failure (if enabled)
-11. Cleans old backups (keeps last 10)
-
-**Parameters**:
- `-InstallPath` (default: `C:\inetpub\wwwroot\roa2web\telegram-bot`)
- `-SourcePath` (auto-detected)
- `-BackupEnabled`, `-RestartService`, `-RollbackOnFailure`
-
---
-
-### ⚙️ Service Management
-
-#### **Manage-ROA2WEB.ps1** ⭐ (UNIFIED - Recommended)
-**Purpose**: Unified service management for all components
-
-**Usage**:
-```powershell
-# Start all services
-.\Manage-ROA2WEB.ps1 -Action Start
-
-# Stop all services
-.\Manage-ROA2WEB.ps1 -Action Stop
-
-# Restart all services
-.\Manage-ROA2WEB.ps1 -Action Restart
-
-# Check status of all services
-.\Manage-ROA2WEB.ps1 -Action Status
-
-# Manage specific component
-.\Manage-ROA2WEB.ps1 -Action Start -Component Backend
-.\Manage-ROA2WEB.ps1 -Action Restart -Component TelegramBot
-.\Manage-ROA2WEB.ps1 -Action Status -Component Backend
-```
-
-**Parameters**:
- `-Action` Start|Stop|Restart|Status (required)
- `-Component` All|Backend|TelegramBot (default: All)
- `-Timeout` (default: 30 seconds)
-
-**Features**:
- ✅ Health checks after start operations
- ✅ Colored status output
- ✅ Detailed error messages
- ✅ Administrator privilege verification
-
---
-
-#### Start-ROA2WEB.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Start -Component Backend`
-
---
-
-#### Stop-ROA2WEB.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Stop -Component Backend`
-
---
-
-#### Restart-ROA2WEB.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Restart -Component Backend`
-
---
-
-#### Start-TelegramBot.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Start -Component TelegramBot`
-
---
-
-#### Stop-TelegramBot.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Stop -Component TelegramBot`
-
---
-
-#### Restart-TelegramBot.ps1 ⚠️ REMOVED
-**Status**: Removed - Use `Manage-ROA2WEB.ps1 -Action Restart -Component TelegramBot`
-
---
-
 ### 🛠️ Utility Scripts

 #### **Backup-TelegramDB.ps1**
@@ -326,124 +253,239 @@ Use: `.\Build-ROA2WEB.ps1 -Component TelegramBot` instead

 ---

-## 📊 Script Comparison Matrix
+## 🚀 Quick Reference Guide

-| Feature | Build-ROA2WEB | Build-Frontend | Build-TelegramBot | Manage-ROA2WEB | Old Start/Stop |
-|---------|---------------|----------------|-------------------|----------------|----------------|
-| **Status** | ✅ Active | ⚠️ Deprecated | ⚠️ Deprecated | ✅ Active | 🗑️ Removed |
-| **Components** | All | Frontend+Backend | TelegramBot | All | Single |
-| **Unified** | ✅ Yes | ❌ No | ❌ No | ✅ Yes | ❌ No |
-| **Flexible** | ✅ High | ⚠️ Medium | ⚠️ Medium | ✅ High | ❌ Low |
-| **Health Checks** | ✅ Yes | ❌ No | ❌ No | ✅ Yes | ⚠️ Basic |
-
---
-
-## 🚀 Quick Reference
-
-### First-Time Deployment
+### 📦 First-Time Deployment Workflow

 ```powershell
-# 1. Build on development machine
+# ========================================
+# STEP 1: Build on Development Machine (WSL/Linux)
+# ========================================
 cd deployment/windows/scripts
 .\Build-ROA2WEB.ps1
+# Select [1] All Components from menu

-# 2. Transfer deploy-package/ to server
+# ========================================
+# STEP 2: Transfer Package to Windows Server
+# ========================================
+# Transfer deploy-package/ to server (e.g., C:\Deploy\roa2web-package)

-# 3. Install on server (as Administrator)
-cd C:\Deploy\deploy-package\scripts
+# ========================================
+# STEP 3: Install on Windows Server (as Administrator)
+# ========================================
+cd C:\Deploy\roa2web-package\scripts
+
+# Install Backend + Frontend
 .\Install-ROA2WEB.ps1
+
+# Install Telegram Bot
 .\Install-TelegramBot.ps1

-# 4. Configure
+# ========================================
+# STEP 4: Configure
+# ========================================
 notepad C:\inetpub\wwwroot\roa2web\backend\.env
 notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

-# 5. Start services
-.\Manage-ROA2WEB.ps1 -Action Start
-```
-
-### Deploy Updates
-
-```powershell
-# 1. Build new package on development machine
-.\Build-ROA2WEB.ps1
-
-# 2. Transfer to server
-
-# 3. Deploy (as Administrator)
-cd C:\Deploy\new-package\scripts
-.\Manage-ROA2WEB.ps1 -Action Stop
-.\Deploy-ROA2WEB.ps1
-.\Deploy-TelegramBot.ps1
-.\Manage-ROA2WEB.ps1 -Action Start
-```
-
-### Daily Operations
-
-```powershell
-# Check status
-.\Manage-ROA2WEB.ps1 -Action Status
-
-# Restart services
-.\Manage-ROA2WEB.ps1 -Action Restart
-
-# Restart specific component
-.\Manage-ROA2WEB.ps1 -Action Restart -Component Backend
-
-# Backup database
-.\Backup-TelegramDB.ps1
+# ========================================
+# STEP 5: Start Services via Console
+# ========================================
+.\ROA2WEB-Console.ps1
+# Select [2] Manage Services -> [1] Start All Services
 ```

 ---

-## 📝 Notes
+### 🔄 Deploy Updates Workflow

- **Administrator Privileges**: All scripts require PowerShell as Administrator
- **Automatic Backups**: Deploy scripts create backups before updating
- **Health Checks**: Manage-ROA2WEB.ps1 validates services after starting
- **Rollback Support**: Deploy-TelegramBot.ps1 supports automatic rollback on failure
- **Configuration Preservation**: .env files are never overwritten during updates
- **Dependency Management**: Scripts only reinstall Python packages if requirements.txt changes
+```powershell
+# ========================================
+# STEP 1: Build New Package on Development Machine
+# ========================================
+cd deployment/windows/scripts
+.\Build-ROA2WEB.ps1
+# Select component to update from menu
+
+# ========================================
+# STEP 2: Transfer to Windows Server
+# ========================================
+# Transfer new deploy-package/ to server
+
+# ========================================
+# STEP 3: Deploy via Console (as Administrator)
+# ========================================
+cd C:\Deploy\new-package\scripts
+.\ROA2WEB-Console.ps1
+
+# Option A: Interactive Menu
+# [1] Deploy Components -> Select what to deploy
+
+# Option B: Non-Interactive
+.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
+```
+
+---
+
+### 🎛️ Daily Operations via Console
+
+```powershell
+# Launch console
+.\ROA2WEB-Console.ps1
+
+# Main Menu Navigation:
+# [1] Deploy Components   -> Deploy/update application files
+# [2] Manage Services     -> Start/Stop/Restart services
+# [3] Check Status        -> View service status and health
+# [Q] Quit
+
+# Non-Interactive Quick Commands:
+.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
+.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartAll
+```
+
+---
+
+### 📊 Utility Operations
+
+```powershell
+# Backup database
+.\Backup-TelegramDB.ps1
+
+# Setup automated daily backups
+.\Setup-DailyBackup.ps1 -Time "02:00" -RetentionDays 14
+
+# Configure Claude API
+.\Setup-ClaudeAuth.ps1
+
+# Enable HTTPS
+.\Enable-HTTPS.ps1
+```
+
+---
+
+## 📊 Script Comparison: v1.0 vs v2.0
+
+| Capability | v1.0 (Old) | v2.0 (Unified) |
+|-----------|-----------|----------------|
+| **Build Scripts** | 3 separate | 1 unified (`Build-ROA2WEB.ps1`) |
+| **Deploy Scripts** | 2 separate | 1 unified console (`ROA2WEB-Console.ps1`) |
+| **Manage Scripts** | 1 basic | Integrated in console |
+| **Total Scripts** | 13 scripts | 8 scripts |
+| **Interactive Menus** | ❌ No | ✅ Yes |
+| **Non-Interactive Mode** | ⚠️ Partial | ✅ Full support |
+| **Health Checks** | ⚠️ Basic | ✅ Comprehensive |
+| **Backup Management** | ⚠️ Manual | ✅ Automatic |
+| **Dependency Updates** | ⚠️ Always reinstall | ✅ Smart (only if changed) |
+| **WSL Compatibility** | ❌ Corrupts node_modules | ✅ Isolated builds |
+
+---
+
+## 🗂️ Complete Script List (v2.0)
+
+### Core Scripts (2)
+1. ⭐ **Build-ROA2WEB.ps1** - Unified build system with menu
+2. ⭐ **ROA2WEB-Console.ps1** - Unified deployment & management console
+
+### Installation Scripts (2)
+3. **Install-ROA2WEB.ps1** - First-time Backend + Frontend setup
+4. **Install-TelegramBot.ps1** - First-time Telegram Bot setup
+
+### Utility Scripts (4)
+5. **Backup-TelegramDB.ps1** - Database backup
+6. **Setup-DailyBackup.ps1** - Automated backup scheduling
+7. **Setup-ClaudeAuth.ps1** - Claude API configuration
+8. **Enable-HTTPS.ps1** - HTTPS setup for IIS
+
+### Removed Scripts (5)
+- ❌ `Build-Frontend.ps1` → Use `Build-ROA2WEB.ps1 -Component Frontend`
+- ❌ `Build-TelegramBot.ps1` → Use `Build-ROA2WEB.ps1 -Component TelegramBot`
+- ❌ `Deploy-ROA2WEB.ps1` → Use `ROA2WEB-Console.ps1` menu option [1] Deploy
+- ❌ `Deploy-TelegramBot.ps1` → Use `ROA2WEB-Console.ps1` menu option [1] Deploy
+- ❌ `Manage-ROA2WEB.ps1` → Use `ROA2WEB-Console.ps1` menu option [2] Manage
+
+---
+
+## 💡 Best Practices
+
+### Development Machine (WSL/Linux)
+```powershell
+# Always use Build-ROA2WEB.ps1 for building
+# It isolates npm builds to prevent WSL corruption
+.\Build-ROA2WEB.ps1
+```
+
+### Windows Server
+```powershell
+# Use ROA2WEB-Console.ps1 for all operations
+# Interactive mode for manual operations
+.\ROA2WEB-Console.ps1
+
+# Non-interactive mode for automation/scripts
+.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
+```
+
+### Configuration Management
+- ✅ `.env` files are NEVER overwritten during deployment
+- ✅ Backups are created automatically before any deployment
+- ✅ Old backups are auto-cleaned (keeps last 10)
+- ✅ Dependencies only reinstalled if `requirements.txt` changes
+
+### Service Management
+- ✅ Always use ROA2WEB-Console for service operations
+- ✅ Health checks are automatic after service starts
+- ✅ Color-coded output makes status clear
+- ✅ Services can be managed individually or together

 ---

 ## 🐛 Troubleshooting

 ### Script Execution Policy Error
-
 ```powershell
 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 ```

+### Build Fails on WSL
+- Ensure Node.js 16+ is installed: `node -v`
+- Close all IDEs (file locks prevent builds)
+- Run as Administrator in PowerShell
+
 ### Service Won't Start
-
 ```powershell
-# Check service status
-.\Manage-ROA2WEB.ps1 -Action Status
+# Check status via console
+.\ROA2WEB-Console.ps1 -NonInteractive -Action Status

-# View logs
+# View backend logs
 Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
+
+# View Telegram bot logs
 Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50
 ```

-### Build Fails
+### Deployment Fails
+```powershell
+# ROA2WEB-Console.ps1 creates automatic backups
+# Check backup location if rollback needed
+Get-ChildItem C:\inetpub\wwwroot\roa2web\backups\ | Sort-Object Name -Descending
+```

- Ensure Node.js 16+ is installed (for Frontend builds)
- Close VS Code and IDEs (file locks)
- Run as Administrator
+### Frontend Build Corrupts WSL node_modules
+- ✅ **Fixed in v2.0!** Build-ROA2WEB.ps1 uses isolated temp directory
+- The temp directory is automatically cleaned after build

 ---

 ## 📚 Documentation

- **Deployment Package Guide**: [`../DEPLOY_PACKAGE.md`](../DEPLOY_PACKAGE.md)
- **Complete Deployment Guide**: [`../docs/WINDOWS_DEPLOYMENT.md`](../docs/WINDOWS_DEPLOYMENT.md)
- **Troubleshooting**: [`../docs/TELEGRAM_BOT_TROUBLESHOOTING.md`](../docs/TELEGRAM_BOT_TROUBLESHOOTING.md)
 - **Quick Start**: [`../README.md`](../README.md)
+- **Complete Deployment Guide**: [`../docs/WINDOWS_DEPLOYMENT.md`](../docs/WINDOWS_DEPLOYMENT.md)
+- **Deployment Package Guide**: [`../DEPLOY_PACKAGE.md`](../DEPLOY_PACKAGE.md)
+- **Telegram Bot Troubleshooting**: [`../docs/TELEGRAM_BOT_TROUBLESHOOTING.md`](../docs/TELEGRAM_BOT_TROUBLESHOOTING.md)
+- **HTTPS Setup**: [`../docs/HTTPS_SETUP.md`](../docs/HTTPS_SETUP.md)
 - **Project Documentation**: [`../../../CLAUDE.md`](../../../CLAUDE.md)

 ---

 **Version**: 2.0 (Unified System)
-**Last Updated**: 2025-11-11
+**Last Updated**: 2025-11-12
 **Author**: ROA2WEB Team