# 🛠️ 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**:
```powershell
# 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**:
```powershell
.\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**:
```powershell
.\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**:
```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**
**Purpose**: Backup Telegram bot SQLite database

**Usage**:
```powershell
# 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**:
```powershell
# 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**:
```powershell
.\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**:
```powershell
# 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

```powershell
# 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

```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
```

---

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

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Service Won't Start

```powershell
# 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`](../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)
- **Project Documentation**: [`../../../CLAUDE.md`](../../../CLAUDE.md)

---

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