refactor(docs): consolidate and cleanup documentation
- Delete 9 deprecated/obsolete docs (~6,300 lines removed) - Move test PDFs to tests/fixtures/ocr-samples/ - Create docs/DEPLOYMENT.md as principal guide - Create tests/ocr-validation/README.md - Update all refs for ultrathin monolith architecture - Update OCR tests to use relative paths Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Agent
192
docs/DEPLOYMENT.md
Normal file
192
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# ROA2WEB Deployment Guide
|
||||
|
||||
**Arhitectură:** Ultrathin Monolith | **Serviciu:** `ROA2WEB-Backend` (port 8000)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
ROA2WEB folosește o arhitectură **ultrathin monolith** - un singur serviciu backend care gestionează toate modulele:
|
||||
|
||||
| Modul | Descriere | Control |
|
||||
|-------|-----------|---------|
|
||||
| Reports | Rapoarte read-only din Oracle | `MODULE_REPORTS_ENABLED` |
|
||||
| Data Entry | Input date cu workflow aprobare | `MODULE_DATA_ENTRY_ENABLED` |
|
||||
| Telegram | Bot Telegram integrat | `MODULE_TELEGRAM_ENABLED` |
|
||||
|
||||
**Avantaje:**
|
||||
- Single Windows/Linux service de gestionat
|
||||
- Shared database connection pool
|
||||
- Deployment simplificat
|
||||
- Consum redus de memorie
|
||||
|
||||
---
|
||||
|
||||
## Quick Deploy
|
||||
|
||||
### Din Linux/LXC (Recomandat)
|
||||
|
||||
```bash
|
||||
cd deployment/linux
|
||||
./deploy.sh # Full deploy (frontend + backend)
|
||||
./deploy.sh frontend # Doar frontend
|
||||
./deploy.sh backend # Doar backend
|
||||
./deploy.sh test # Test conexiune SSH
|
||||
```
|
||||
|
||||
**Detalii:** [deployment/linux/README.md](../deployment/linux/README.md)
|
||||
|
||||
### Din Windows
|
||||
|
||||
```powershell
|
||||
cd deployment\windows\scripts
|
||||
.\Publish-And-Deploy.ps1
|
||||
|
||||
# Non-interactiv:
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All
|
||||
```
|
||||
|
||||
**Detalii:** [deployment/windows/README.md](../deployment/windows/README.md)
|
||||
|
||||
---
|
||||
|
||||
## Deployment Flow
|
||||
|
||||
```
|
||||
DEV MACHINE WINDOWS SERVER
|
||||
─────────── ──────────────
|
||||
|
||||
deploy.sh (Linux)
|
||||
sau ───► C:\Temp\deploy-*\
|
||||
Publish-And-Deploy.ps1 │
|
||||
▼
|
||||
Check-And-Deploy.ps1
|
||||
(scheduled task, 5 min)
|
||||
│
|
||||
▼
|
||||
ROA2WEB-Console.ps1
|
||||
├── Stop Service
|
||||
├── Backup
|
||||
├── Deploy Files
|
||||
├── Start Service
|
||||
└── Health Check
|
||||
│
|
||||
▼
|
||||
✅ PRODUCTION RUNNING
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server Configuration
|
||||
|
||||
### Structura pe Server
|
||||
|
||||
```
|
||||
C:\inetpub\wwwroot\roa2web\
|
||||
├── backend\ # FastAPI (toate modulele)
|
||||
│ └── .env # MODULE_*_ENABLED flags
|
||||
├── frontend\ # Vue.js SPA + web.config
|
||||
├── shared\ # Module Python partajate
|
||||
├── logs\ # backend-stdout.log, backend-stderr.log
|
||||
└── backups\ # Backup-uri automate
|
||||
```
|
||||
|
||||
### Configurare Modul (.env)
|
||||
|
||||
```bash
|
||||
# Module enable/disable
|
||||
MODULE_REPORTS_ENABLED=true
|
||||
MODULE_DATA_ENTRY_ENABLED=true
|
||||
MODULE_TELEGRAM_ENABLED=true
|
||||
|
||||
# Database
|
||||
ORACLE_DSN=localhost:1521/ORCL
|
||||
ORACLE_USER=contafin
|
||||
ORACLE_PASSWORD=***
|
||||
|
||||
# Auth
|
||||
JWT_SECRET_KEY=your-secret-key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Client → IIS (80/443)
|
||||
│
|
||||
├─ /roa2web/api/* → ROA2WEB-Backend (localhost:8000)
|
||||
│ ├── Reports Module → Oracle DB
|
||||
│ ├── Data Entry Module → SQLite
|
||||
│ └── Telegram Module (background task)
|
||||
│
|
||||
└─ /roa2web/* → Frontend (Vue.js SPA)
|
||||
```
|
||||
|
||||
### Single Worker Requirement
|
||||
|
||||
**IMPORTANT:** Backend-ul TREBUIE rulat cu `--workers 1` pentru:
|
||||
- Telegram bot (un singur bot instance permis)
|
||||
- SQLite cache (evită conflicte de locking)
|
||||
|
||||
**Detalii:** [docs/telegram/DEPLOYMENT.md](./telegram/DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Guides
|
||||
|
||||
| Platform | Guide | Scop |
|
||||
|----------|-------|------|
|
||||
| **Linux/LXC** | [deployment/linux/README.md](../deployment/linux/README.md) | Deploy din container Linux |
|
||||
| **Windows** | [deployment/windows/README.md](../deployment/windows/README.md) | IIS setup, Windows service |
|
||||
| **HTTPS** | [deployment/windows/docs/HTTPS_SETUP.md](../deployment/windows/docs/HTTPS_SETUP.md) | SSL certificate setup |
|
||||
| **2-Tier IIS** | [deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md](../deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md) | Public → Internal architecture |
|
||||
| **Auto-Deploy** | [deployment/windows/docs/DEPLOYMENT_AUTOMATION.md](../deployment/windows/docs/DEPLOYMENT_AUTOMATION.md) | Scheduled task automation |
|
||||
|
||||
---
|
||||
|
||||
## web.config Files
|
||||
|
||||
| Fișier | Scop | Când se folosește |
|
||||
|--------|------|-------------------|
|
||||
| `public/web.config` | Sub-aplicație IIS (/roa2web) | La fiecare deploy (via Vite) |
|
||||
| `deployment/windows/config/web.config` | Server IIS complet | La instalare nouă |
|
||||
|
||||
**Notă:** Ambele au configurat `no-cache` pentru API (backend gestionează cache-ul).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problemă | Verificare | Soluție |
|
||||
|----------|------------|---------|
|
||||
| Service nu pornește | Logs: `backend-stderr.log` | Verifică `.env`, port 8000 |
|
||||
| API 502/504 | `curl http://localhost:8000/health` | Restart service |
|
||||
| Frontend nu se încarcă | `iisreset` | Verifică IIS, web.config |
|
||||
| Auto-deploy nu merge | `Get-ScheduledTask ROA2WEB-AutoDeploy` | Re-run setup script |
|
||||
| Telegram conflicts | Logs: "terminated by other getUpdates" | Ensure `--workers 1` |
|
||||
|
||||
---
|
||||
|
||||
## System Requirements
|
||||
|
||||
| Resursă | Minim | Recomandat |
|
||||
|---------|-------|------------|
|
||||
| OS | Windows Server 2016 / Ubuntu 20.04 | Windows Server 2019+ |
|
||||
| RAM | 4 GB | 8 GB (16 GB cu OCR) |
|
||||
| CPU | 2 cores | 4 cores |
|
||||
| Python | 3.11+ | 3.11+ |
|
||||
| IIS | URL Rewrite + ARR | URL Rewrite + ARR |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [ARCHITECTURE-DECISIONS.md](./ARCHITECTURE-DECISIONS.md) - ADR-uri importante
|
||||
- [MONOLITH_ARCHITECTURE.md](./MONOLITH_ARCHITECTURE.md) - Arhitectura detaliată
|
||||
- [telegram/DEPLOYMENT.md](./telegram/DEPLOYMENT.md) - Single worker requirement
|
||||
|
||||
---
|
||||
|
||||
*ROA2WEB - Ultrathin Monolith Architecture*
|
||||
*Last Updated: 2026-01-22*
|
||||
Reference in New Issue
Block a user