Initial commit: ROA2WEB - FastAPI + Vue.js + Telegram Bot
Modern ERP Reports Application with microservices architecture Tech Stack: - Backend: FastAPI + python-oracledb (Oracle DB integration) - Frontend: Vue.js 3 + PrimeVue + Vite - Telegram Bot: python-telegram-bot + SQLite - Infrastructure: Shared database pool, JWT authentication, SSH tunnel Features: - FastAPI backend with async Oracle connection pool - Vue.js 3 responsive frontend with PrimeVue components - Telegram bot alternative interface - Microservices architecture with shared components - Complete deployment support (Linux Docker + Windows IIS) - Comprehensive testing (Playwright E2E + pytest) Repository Structure: - reports-app/ - Main application (backend, frontend, telegram-bot) - shared/ - Shared components (database pool, auth, utils) - deployment/ - Deployment scripts (Linux & Windows) - docs/ - Project documentation - security/ - Security scanning and git hooks
This commit is contained in:
361
deployment/windows/README.md
Normal file
361
deployment/windows/README.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# ROA2WEB - Windows Deployment Package
|
||||
|
||||
Complete deployment solution for ROA2WEB on Windows Server with IIS and Oracle Database.
|
||||
|
||||
---
|
||||
|
||||
## 📂 Package Contents
|
||||
|
||||
```
|
||||
deployment/windows/
|
||||
├── config/ # Configuration files
|
||||
│ ├── web.config # IIS configuration (URL Rewrite, reverse proxy)
|
||||
│ └── .env.production.windows # Environment variables template
|
||||
│
|
||||
├── scripts/ # PowerShell automation scripts
|
||||
│ ├── Install-ROA2WEB.ps1 # Initial installation
|
||||
│ ├── Deploy-ROA2WEB.ps1 # Deploy updates
|
||||
│ ├── Build-Frontend.ps1 # Build Vue.js frontend (run locally)
|
||||
│ ├── Start-ROA2WEB.ps1 # Start backend service
|
||||
│ ├── Stop-ROA2WEB.ps1 # Stop backend service
|
||||
│ └── Restart-ROA2WEB.ps1 # Restart backend service
|
||||
│
|
||||
├── docs/ # Documentation
|
||||
│ └── WINDOWS_DEPLOYMENT.md # Complete deployment guide
|
||||
│
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Windows Server** 2016+ (or Windows 10/11 Pro)
|
||||
- **IIS** installed
|
||||
- **Oracle Database** (local or network-accessible)
|
||||
- **PowerShell 5.1+**
|
||||
- **Administrator privileges**
|
||||
|
||||
### Installation Steps
|
||||
|
||||
#### 1. Build Frontend (on development machine)
|
||||
|
||||
```bash
|
||||
# On WSL/Linux/Mac
|
||||
cd roa2web/deployment/windows/scripts
|
||||
./Build-Frontend.ps1
|
||||
|
||||
# This creates: ./deploy-package/
|
||||
```
|
||||
|
||||
#### 2. Transfer to Server
|
||||
|
||||
Copy the entire project to Windows Server:
|
||||
```
|
||||
C:\roa2web\deployment\windows\
|
||||
```
|
||||
|
||||
#### 3. Run Installation
|
||||
|
||||
```powershell
|
||||
# On Windows Server (PowerShell as Administrator)
|
||||
cd C:\roa2web\deployment\windows\scripts
|
||||
|
||||
# Install everything
|
||||
.\Install-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
This will:
|
||||
- ✅ Install Python 3.11+
|
||||
- ✅ Install NSSM (service manager)
|
||||
- ✅ Install IIS URL Rewrite and ARR
|
||||
- ✅ Create directory structure
|
||||
- ✅ Install Python dependencies
|
||||
- ✅ Create Windows Service
|
||||
- ✅ Configure IIS website
|
||||
|
||||
#### 4. Configure Application
|
||||
|
||||
```powershell
|
||||
# Copy and edit environment file
|
||||
Copy-Item C:\inetpub\wwwroot\roa2web\backend\config\.env.production.windows `
|
||||
C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Edit with your values
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
```
|
||||
|
||||
**Required settings:**
|
||||
|
||||
Configure these variables in `.env`:
|
||||
- Database credentials (user, password, host, port, SID)
|
||||
- JWT secret key for authentication
|
||||
- Other application-specific settings
|
||||
|
||||
Example structure:
|
||||
```env
|
||||
ORACLE_USER=CONTAFIN_ORACLE
|
||||
ORACLE_HOST=localhost
|
||||
ORACLE_PORT=1521
|
||||
ORACLE_SID=ROA
|
||||
# Add password and JWT secret here
|
||||
```
|
||||
|
||||
#### 5. Deploy Application Files
|
||||
|
||||
```powershell
|
||||
# Deploy frontend and backend
|
||||
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"
|
||||
```
|
||||
|
||||
#### 6. Verify Installation
|
||||
|
||||
```powershell
|
||||
# Check service
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# Test backend
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
|
||||
# Open application
|
||||
Start-Process "http://localhost"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Update Workflow
|
||||
|
||||
For deploying updates to existing installation:
|
||||
|
||||
**1. Build on development machine:**
|
||||
```bash
|
||||
cd roa2web/deployment/windows/scripts
|
||||
./Build-Frontend.ps1 -OutputPath "./deploy-$(date +%Y%m%d)"
|
||||
```
|
||||
|
||||
**2. Transfer to server:**
|
||||
```powershell
|
||||
Copy-Item .\deploy-20250118 -Destination C:\Temp\roa2web-deploy -Recurse
|
||||
```
|
||||
|
||||
**3. Deploy on server:**
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\deployment\windows\scripts
|
||||
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\Temp\roa2web-deploy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Management Commands
|
||||
|
||||
```powershell
|
||||
# Start backend service
|
||||
.\Start-ROA2WEB.ps1
|
||||
|
||||
# Stop backend service
|
||||
.\Stop-ROA2WEB.ps1
|
||||
|
||||
# Restart backend service
|
||||
.\Restart-ROA2WEB.ps1
|
||||
|
||||
# View logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log -Tail 50 -Wait
|
||||
|
||||
# Check service status
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# Check IIS website
|
||||
Get-Website ROA2WEB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Architecture
|
||||
|
||||
### Components
|
||||
|
||||
| Component | Type | Port | Purpose |
|
||||
|-----------|------|------|---------|
|
||||
| **Frontend** | IIS Static Files | 80/443 | Vue.js SPA |
|
||||
| **Backend** | Windows Service | 8000 | FastAPI API |
|
||||
| **Database** | Oracle | 1521 | Data storage |
|
||||
| **Reverse Proxy** | IIS URL Rewrite | - | API routing |
|
||||
|
||||
### Network Flow
|
||||
|
||||
```
|
||||
Client → IIS (port 80) → [web.config URL Rewrite]
|
||||
├─ /api/* → Backend Service (localhost:8000)
|
||||
│ ↓
|
||||
│ Oracle DB (localhost:1521)
|
||||
└─ /* → Static Files (Vue.js)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Directory Structure After Installation
|
||||
|
||||
```
|
||||
C:\inetpub\wwwroot\roa2web\
|
||||
├── backend\ # FastAPI application
|
||||
│ ├── app\
|
||||
│ ├── requirements.txt
|
||||
│ ├── .env # Configuration
|
||||
│ └── logs\
|
||||
│
|
||||
├── frontend\ # Vue.js static files
|
||||
│ ├── index.html
|
||||
│ ├── assets\
|
||||
│ └── web.config
|
||||
│
|
||||
├── logs\ # Service logs
|
||||
│ ├── backend-stdout.log
|
||||
│ └── backend-stderr.log
|
||||
│
|
||||
└── backups\ # Automatic backups
|
||||
└── backup-YYYYMMDD-HHMMSS\
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### Service won't start
|
||||
|
||||
```powershell
|
||||
# Check logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
|
||||
|
||||
# Test manually
|
||||
cd C:\inetpub\wwwroot\roa2web\backend
|
||||
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||||
```
|
||||
|
||||
### Frontend not loading
|
||||
|
||||
```powershell
|
||||
# Restart IIS
|
||||
iisreset
|
||||
|
||||
# Check website status
|
||||
Get-Website ROA2WEB
|
||||
Start-Website ROA2WEB
|
||||
```
|
||||
|
||||
### API calls failing (502/504)
|
||||
|
||||
```powershell
|
||||
# Check backend service
|
||||
Get-Service ROA2WEB-Backend
|
||||
.\Restart-ROA2WEB.ps1
|
||||
|
||||
# Test backend directly
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
### Database connection issues
|
||||
|
||||
```powershell
|
||||
# Test Oracle connection
|
||||
sqlplus CONTAFIN_ORACLE/password@localhost:1521/ROA
|
||||
|
||||
# Check Oracle service
|
||||
Get-Service Oracle*
|
||||
|
||||
# Check .env configuration
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\.env | Select-String ORACLE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Full Documentation
|
||||
|
||||
For complete documentation, see:
|
||||
- **[WINDOWS_DEPLOYMENT.md](docs/WINDOWS_DEPLOYMENT.md)** - Comprehensive deployment guide
|
||||
- **[.env.production.windows](config/.env.production.windows)** - Configuration reference
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Key Features
|
||||
|
||||
✅ **Simple Installation** - One PowerShell script installs everything
|
||||
✅ **Minimal Dependencies** - Only Python + IIS (already on Windows Server)
|
||||
✅ **Easy Replication** - Same scripts work on all servers
|
||||
✅ **Automatic Backups** - Every deployment creates a backup
|
||||
✅ **Windows Service** - Backend runs as service with auto-start/restart
|
||||
✅ **Production Ready** - Optimized for performance and reliability
|
||||
|
||||
---
|
||||
|
||||
## 📊 System Requirements
|
||||
|
||||
| Resource | Minimum | Recommended |
|
||||
|----------|---------|-------------|
|
||||
| **OS** | Windows Server 2016 | Windows Server 2019+ |
|
||||
| **RAM** | 4 GB | 8 GB |
|
||||
| **CPU** | 2 cores | 4 cores |
|
||||
| **Disk** | 10 GB free | 20 GB free |
|
||||
| **Network** | 100 Mbps | 1 Gbps |
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Recommendations
|
||||
|
||||
1. **Generate Strong JWT Secret:**
|
||||
```powershell
|
||||
-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})
|
||||
```
|
||||
|
||||
2. **Secure .env File:**
|
||||
```powershell
|
||||
icacls C:\inetpub\wwwroot\roa2web\backend\.env /inheritance:r /grant:r Administrators:F
|
||||
```
|
||||
|
||||
3. **Enable HTTPS:** ⭐ **RECOMMENDED**
|
||||
```powershell
|
||||
# Quick setup with automated script
|
||||
cd C:\roa2web\deployment\windows\scripts
|
||||
.\Enable-HTTPS.ps1
|
||||
|
||||
# For detailed instructions, see:
|
||||
# docs/HTTPS_SETUP.md
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Creates/installs SSL certificate
|
||||
- Configures HTTPS binding (port 443)
|
||||
- Enables HTTP to HTTPS redirect
|
||||
- Activates HSTS (Strict Transport Security)
|
||||
|
||||
**Access your application securely:**
|
||||
- `https://10.0.20.36/roa2web` (or your domain)
|
||||
|
||||
4. **Regular Updates:**
|
||||
- Keep Windows Server updated
|
||||
- Update Python packages monthly
|
||||
- Monitor security advisories
|
||||
- Renew SSL certificates before expiry
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check logs: `C:\inetpub\wwwroot\roa2web\logs\`
|
||||
2. Review [WINDOWS_DEPLOYMENT.md](docs/WINDOWS_DEPLOYMENT.md)
|
||||
3. Contact: development-team@your-company.com
|
||||
|
||||
---
|
||||
|
||||
## 📝 Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 2.0.0 | 2025-01-18 | Initial Windows deployment package |
|
||||
|
||||
---
|
||||
|
||||
*ROA2WEB - Modern ERP Reports Application*
|
||||
*Windows Server Deployment Package v2.0.0*
|
||||
Reference in New Issue
Block a user