roa2web-service-auto/deployment/windows/DEPLOY_PACKAGE.md

📦 Deployment Package Generation

This document explains how to generate deployment packages for ROA2WEB Windows deployment.

⚠️ Important Note

The deploy-package/ directory is NOT committed to git. It contains build artifacts that are generated fresh each time you build.

🔨 Generating Deployment Packages

Use the unified build script Build-ROA2WEB.ps1 to generate deployment packages:

Build Complete Package (Recommended)

cd deployment/windows/scripts
.\Build-ROA2WEB.ps1

This generates a complete deployment package containing:

• ✅ Frontend (Vue.js built static files)
• ✅ Backend (FastAPI Python application)
• ✅ Shared modules (auth, database, utils)
• ✅ Telegram Bot application
• ✅ Configuration templates
• ✅ Deployment scripts

Output: deployment/windows/deploy-package/

Build Specific Components

# Frontend + Backend only
.\Build-ROA2WEB.ps1 -Component Frontend

# Backend only (no frontend build)
.\Build-ROA2WEB.ps1 -Component Backend

# Telegram Bot only
.\Build-ROA2WEB.ps1 -Component TelegramBot

Custom Output Path

# Build to custom location with date suffix
.\Build-ROA2WEB.ps1 -OutputPath "D:\deployments\roa2web-$(Get-Date -Format 'yyyyMMdd')"

📂 Package Structure

After building, deploy-package/ will contain:

deploy-package/
├── backend/                    # FastAPI application files
│   ├── app/                    # Application code
│   ├── requirements.txt        # Python dependencies
│   └── ...
├── frontend/                   # Built Vue.js static files
│   ├── assets/                 # JS, CSS, fonts
│   ├── index.html              # Main HTML
│   └── ...
├── telegram-bot/               # Telegram bot application
│   ├── app/                    # Bot code
│   ├── requirements.txt        # Bot dependencies
│   └── .env.example            # Configuration template
├── shared/                     # Shared Python modules
│   ├── auth/                   # Authentication
│   ├── database/               # Oracle connection pool
│   └── utils/                  # Utilities
├── config/                     # Configuration templates
│   ├── .env.production.windows
│   ├── .env.production.windows.telegram
│   └── web.config              # IIS configuration
├── scripts/                    # Deployment scripts
│   ├── Install-ROA2WEB.ps1
│   ├── Install-TelegramBot.ps1
│   ├── Deploy-ROA2WEB.ps1
│   ├── Deploy-TelegramBot.ps1
│   ├── Manage-ROA2WEB.ps1
│   ├── Backup-TelegramDB.ps1
│   ├── Setup-DailyBackup.ps1
│   ├── Setup-ClaudeAuth.ps1
│   └── Enable-HTTPS.ps1
└── README.txt                  # Deployment instructions

🚀 Deployment Workflow

1. Build Package (Development Machine)

# On WSL or development machine
cd deployment/windows/scripts
.\Build-ROA2WEB.ps1

2. Transfer to Windows Server

# Via network share
Copy-Item -Path ./deploy-package -Destination \\SERVER\C$\Temp\roa2web-deploy -Recurse

# Or via RDP (manual copy)

3. Install on Server (First Time)

# On Windows Server (as Administrator)
cd C:\Temp\roa2web-deploy\scripts

# Install main application
.\Install-ROA2WEB.ps1

# Install Telegram bot
.\Install-TelegramBot.ps1

4. Configure & Start

# Configure environment
notepad C:\inetpub\wwwroot\roa2web\backend\.env
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Start services
.\Manage-ROA2WEB.ps1 -Action Start

5. Deploy Updates

# Stop services
.\Manage-ROA2WEB.ps1 -Action Stop

# Deploy updates
.\Deploy-ROA2WEB.ps1
.\Deploy-TelegramBot.ps1

# Start services
.\Manage-ROA2WEB.ps1 -Action Start

🔧 Requirements

Development Machine (for building):

• Node.js 16+ (for Frontend builds)
• npm
• PowerShell 5.1+

Windows Server (for deployment):

• Windows Server 2016+ or Windows 10/11
• IIS with URL Rewrite Module
• Python 3.11+
• PowerShell 5.1+ (Administrator)

📝 Notes

• Build artifacts are NOT version-controlled: The deploy-package/ directory is in .gitignore
• Fresh builds recommended: Always generate a fresh package before deploying
• Virtual environments: Not included in package (created automatically during installation)
• .env files: Not included in package (created from templates during installation)
• Database files: Excluded from package (SQLite for Telegram bot created on server)

⚙️ Advanced Options

Transfer to Server Automatically

# Using network share (Windows)
.\Build-ROA2WEB.ps1 -ServerHost "10.0.20.36" -ServerPath "C:\Temp\roa2web-deploy"

Clean Build

The build script automatically cleans the output directory. To preserve existing output:

.\Build-ROA2WEB.ps1 -Clean $false

🐛 Troubleshooting

"Node.js not found"

Install Node.js 16+ from https://nodejs.org/

"deploy-package already exists"

The script automatically cleans old builds. If you see errors, manually delete deploy-package/ and retry.

Build fails with "locked files"

Close VS Code, IDEs, and file explorers that might have files open in the source directories.

📚 Documentation

• Complete Deployment Guide: docs/WINDOWS_DEPLOYMENT.md
• Script Reference: scripts/README.md
• Quick Start: README.md
• Project Documentation: ../../CLAUDE.md

🔄 Migration from Old Build Scripts

If you were using the old build scripts, here's the mapping:

Old Script	New Script	Equivalent Command
Build-Frontend.ps1	Build-ROA2WEB.ps1	.\Build-ROA2WEB.ps1 -Component Frontend
Build-TelegramBot.ps1	Build-ROA2WEB.ps1	.\Build-ROA2WEB.ps1 -Component TelegramBot
Both scripts together	Build-ROA2WEB.ps1	.\Build-ROA2WEB.ps1 (default: All)

Note: Old scripts are marked as DEPRECATED and will be removed in a future version.

---

Generated by: ROA2WEB Team Last Updated: 2025-11-11 Version: 2.0 (Unified Build System)