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)

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

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

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

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

### 2. Transfer to Windows Server

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

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

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

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

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

```powershell
.\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`](docs/WINDOWS_DEPLOYMENT.md)
- **Script Reference**: [`scripts/README.md`](scripts/README.md)
- **Quick Start**: [`README.md`](README.md)
- **Project Documentation**: [`../../CLAUDE.md`](../../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)