roa2web-service-auto/deployment/windows/scripts/README.md

🛠️ ROA2WEB Windows Deployment Scripts

Complete reference for ROA2WEB Windows deployment PowerShell scripts (v2.0 - Unified System).

📋 Script Overview

🔨 Build Scripts

Build-ROA2WEB.ps1 ⭐ (UNIFIED - Recommended)

Purpose: Unified build script for all components

Usage:

# Build complete package (default)
.\Build-ROA2WEB.ps1

# Build specific components
.\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')"

Parameters:

• -Component All|Frontend|Backend|TelegramBot (default: All)
• -OutputPath (default: ./deploy-package)
• -Clean $true|$false (default: $true)

Output: Creates deploy-package/ with complete deployment files

---

Build-Frontend.ps1 ⚠️ DEPRECATED

Status: Deprecated in favor of Build-ROA2WEB.ps1 -Component Frontend

Use: .\Build-ROA2WEB.ps1 -Component Frontend instead

---

Build-TelegramBot.ps1 ⚠️ DEPRECATED

Status: Deprecated in favor of Build-ROA2WEB.ps1 -Component TelegramBot

Use: .\Build-ROA2WEB.ps1 -Component TelegramBot instead

---

🚀 Installation Scripts

Install-ROA2WEB.ps1

Purpose: First-time installation of Backend + Frontend

Usage:

.\Install-ROA2WEB.ps1

# Custom parameters
.\Install-ROA2WEB.ps1 -InstallPath "C:\Apps\roa2web" -ServicePort 8000

What it does:

1. Installs Chocolatey, Python 3.11+, NSSM
2. Installs IIS URL Rewrite & ARR modules
3. Creates directory structure
4. Creates Python virtual environment
5. Installs Python dependencies
6. Creates Windows Service (ROA2WEB-Backend)
7. Configures IIS website & application

Parameters:

• -InstallPath (default: C:\inetpub\wwwroot\roa2web)
• -ServicePort (default: 8000)
• -IISSiteName, -IISAppName
• -CreateNewSite, -SkipPython, -SkipIIS

---

Install-TelegramBot.ps1

Purpose: First-time installation of Telegram Bot

Usage:

.\Install-TelegramBot.ps1

# Custom parameters
.\Install-TelegramBot.ps1 -InstallPath "C:\Apps\telegram-bot" -ServicePort 8002

What it does:

1. Validates Python 3.11+ installation
2. Installs NSSM (if needed)
3. Creates directory structure (data/, logs/, backups/)
4. Creates Python virtual environment
5. Installs Python dependencies
6. Creates Windows Service (ROA2WEB-TelegramBot)
7. Creates .env template

Parameters:

• -InstallPath (default: C:\inetpub\wwwroot\roa2web\telegram-bot)
• -ServicePort (default: 8002)
• -SourcePath (auto-detected)

---

📦 Deployment Scripts

Deploy-ROA2WEB.ps1

Purpose: Deploy updates to existing Backend + Frontend

Usage:

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

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

# 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

Purpose: Backup Telegram bot SQLite database

Usage:

# Basic backup
.\Backup-TelegramDB.ps1

# Compressed backup
.\Backup-TelegramDB.ps1 -Compress $true

# Keep more backups
.\Backup-TelegramDB.ps1 -RetentionCount 20

What it does:

1. Stops bot service gracefully
2. Creates timestamped backup of telegram_bot.db
3. Optionally compresses backup
4. Restarts service
5. Cleans old backups (configurable retention)

---

Setup-DailyBackup.ps1

Purpose: Schedule automated daily database backups

Usage:

# Setup daily backup at 2 AM
.\Setup-DailyBackup.ps1

# Custom time and retention
.\Setup-DailyBackup.ps1 -Time "03:00" -RetentionDays 30

What it does:

1. Creates Windows Scheduled Task
2. Runs Backup-TelegramDB.ps1 daily at specified time
3. Configurable time, retention, and compression

---

Setup-ClaudeAuth.ps1

Purpose: Setup Claude API authentication for Telegram bot

Usage:

.\Setup-ClaudeAuth.ps1

What it does:

1. Method 1 (Recommended): Browser-based Claude Pro/Max login
   • Runs claude-code login if available
   • Copies credentials to bot installation directory
2. Method 2: Manual API key entry
3. Validates credentials
4. Updates .env file
5. Restarts bot service

Features:

• ✅ Supports both Claude Pro/Max and API key
• ✅ Auto-detects credentials location
• ✅ Validates authentication before applying

---

Enable-HTTPS.ps1

Purpose: Enable HTTPS for IIS website

Usage:

# Create self-signed certificate
.\Enable-HTTPS.ps1

# Use existing certificate
.\Enable-HTTPS.ps1 -CertPath "C:\Certs\roa2web.pfx" -CertPassword "password"

What it does:

1. Creates/imports SSL certificate
2. Configures HTTPS binding (port 443)
3. Enables HTTP to HTTPS redirect
4. Activates HSTS (HTTP Strict Transport Security)

---

📊 Script Comparison Matrix

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

# 1. Build on development machine
cd deployment/windows/scripts
.\Build-ROA2WEB.ps1

# 2. Transfer deploy-package/ to server

# 3. Install on server (as Administrator)
cd C:\Deploy\deploy-package\scripts
.\Install-ROA2WEB.ps1
.\Install-TelegramBot.ps1

# 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

# 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

# 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

---

📝 Notes

• 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

---

🐛 Troubleshooting

Script Execution Policy Error

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Service Won't Start

# Check service status
.\Manage-ROA2WEB.ps1 -Action Status

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

Build Fails

• Ensure Node.js 16+ is installed (for Frontend builds)
• Close VS Code and IDEs (file locks)
• Run as Administrator

---

📚 Documentation

• Deployment Package Guide: ../DEPLOY_PACKAGE.md
• Complete Deployment Guide: ../docs/WINDOWS_DEPLOYMENT.md
• Troubleshooting: ../docs/TELEGRAM_BOT_TROUBLESHOOTING.md
• Quick Start: ../README.md
• Project Documentation: ../../../CLAUDE.md

---

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