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
@@ -1,240 +0,0 @@
|
||||
# web.config Files - Which Goes Where?
|
||||
|
||||
## ⚠️ IMPORTANT - Read Before Deployment!
|
||||
|
||||
ROA2WEB uses a **2-tier IIS architecture** with **2 different web.config files** for **2 different servers**.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Internet
|
||||
↓
|
||||
Public Server (10.0.20.122) - roa2web.romfast.ro
|
||||
↓ HTTPS reverse proxy
|
||||
Internal Server (10.0.20.36) - application host
|
||||
↓ API proxy to localhost
|
||||
Backend Service (localhost:8000 on 10.0.20.36)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Mapping
|
||||
|
||||
### File: `web.config.10.0.20.122-PUBLIC`
|
||||
|
||||
**Server**: 10.0.20.122 (Public IIS - roa2web.romfast.ro)
|
||||
**Role**: Public gateway, reverse proxy to internal server
|
||||
|
||||
**Purpose**:
|
||||
- Proxies ALL requests to `https://10.0.20.36/{REQUEST_PATH}`
|
||||
- Sets forwarding headers (`X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Real-IP`)
|
||||
- Redirects root `/` to `/roa2web/`
|
||||
|
||||
**Key Rule**:
|
||||
```xml
|
||||
<match url="(.*)" />
|
||||
<action type="Rewrite" url="https://10.0.20.36/{R:1}" />
|
||||
```
|
||||
|
||||
**Deployment Location**:
|
||||
```
|
||||
10.0.20.122:
|
||||
C:\inetpub\wwwroot\[ROOT]\web.config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### File: `web.config.10.0.20.36-INTERNAL`
|
||||
|
||||
**Server**: 10.0.20.36 (Internal IIS - application host)
|
||||
**Role**: Serves frontend, proxies API to localhost backend
|
||||
|
||||
**Purpose**:
|
||||
- Serves Vue.js frontend static files
|
||||
- Proxies `/roa2web/api/*` to `http://localhost:8000/api/*`
|
||||
- Proxies `/roa2web/uploads/*` to `http://localhost:8000/uploads/*`
|
||||
- SPA fallback for client-side routing
|
||||
|
||||
**Key Rules**:
|
||||
```xml
|
||||
<match url="^roa2web/api/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
|
||||
<match url="^roa2web/uploads/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/uploads/{R:1}" />
|
||||
|
||||
<match url="^roa2web/.*" />
|
||||
<action type="Rewrite" url="/roa2web/index.html" />
|
||||
```
|
||||
|
||||
**Deployment Location**:
|
||||
```
|
||||
10.0.20.36:
|
||||
C:\inetpub\wwwroot\roa2web\web.config
|
||||
```
|
||||
|
||||
**Note**: This file is also in `public/web.config` (repository root) and is automatically copied to `dist/` during Vite build.
|
||||
|
||||
---
|
||||
|
||||
## Deployment Checklist
|
||||
|
||||
### ✅ Public Server (10.0.20.122)
|
||||
|
||||
```powershell
|
||||
# Copy public server config
|
||||
Copy-Item deployment/windows/config/web.config.10.0.20.122-PUBLIC `
|
||||
C:\inetpub\wwwroot\[ROOT]\web.config
|
||||
|
||||
# Verify
|
||||
Get-Content C:\inetpub\wwwroot\[ROOT]\web.config | Select-String "10.0.20.36"
|
||||
```
|
||||
|
||||
**Expected**: Should see `url="https://10.0.20.36/{R:1}"`
|
||||
|
||||
### ✅ Internal Server (10.0.20.36)
|
||||
|
||||
**Option A: From built dist/ (recommended)**:
|
||||
```powershell
|
||||
# After building frontend with `npm run build`
|
||||
# web.config is automatically in dist/
|
||||
|
||||
# Deploy entire dist/ folder
|
||||
Copy-Item dist\* C:\inetpub\wwwroot\roa2web\ -Recurse -Force
|
||||
```
|
||||
|
||||
**Option B: Manual copy**:
|
||||
```powershell
|
||||
# Copy internal server config
|
||||
Copy-Item deployment/windows/config/web.config.10.0.20.36-INTERNAL `
|
||||
C:\inetpub\wwwroot\roa2web\web.config
|
||||
|
||||
# Verify
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\web.config | Select-String "roa2web/api"
|
||||
```
|
||||
|
||||
**Expected**: Should see `url="^roa2web/api/(.*)"` and `url="http://localhost:8000/api/{R:1}"`
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Public Server (10.0.20.122)
|
||||
|
||||
```powershell
|
||||
# Should proxy to internal server
|
||||
Invoke-WebRequest https://roa2web.romfast.ro/roa2web/ -UseBasicParsing
|
||||
|
||||
# Check response headers
|
||||
(Invoke-WebRequest https://roa2web.romfast.ro/roa2web/).Headers
|
||||
```
|
||||
|
||||
**Expected**: Request should be proxied to 10.0.20.36
|
||||
|
||||
### Test Internal Server (10.0.20.36)
|
||||
|
||||
```powershell
|
||||
# Test backend directly
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
|
||||
# Test through IIS proxy
|
||||
Invoke-WebRequest https://localhost/roa2web/api/health
|
||||
|
||||
# Test frontend
|
||||
Invoke-WebRequest https://localhost/roa2web/
|
||||
```
|
||||
|
||||
**Expected**: All should return 200 OK
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes ❌
|
||||
|
||||
### ❌ WRONG: Using internal config on public server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.122 - WRONG! -->
|
||||
<match url="^roa2web/api/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Public server doesn't have backend on localhost:8000
|
||||
|
||||
### ❌ WRONG: Using public config on internal server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.36 - WRONG! -->
|
||||
<match url="(.*)" />
|
||||
<action type="Rewrite" url="https://10.0.20.36/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Creates infinite redirect loop
|
||||
|
||||
### ❌ WRONG: Missing /roa2web/ prefix on internal server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.36 - WRONG! -->
|
||||
<match url="^api/(.*)" /> <!-- Missing roa2web prefix! -->
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Requests come as `/roa2web/api/...` from public server, so `^api/` won't match
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: 404 on API calls
|
||||
|
||||
**Symptom**: Frontend loads but API returns 404
|
||||
|
||||
**Check**: web.config on 10.0.20.36
|
||||
|
||||
```powershell
|
||||
# On 10.0.20.36
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\web.config | Select-String "roa2web/api"
|
||||
```
|
||||
|
||||
**Fix**: Update to correct internal server config (see above)
|
||||
|
||||
### Issue: Infinite redirect loop
|
||||
|
||||
**Symptom**: Browser shows "Too many redirects"
|
||||
|
||||
**Check**: Verify you didn't put public config on internal server
|
||||
|
||||
### Issue: Backend not reachable
|
||||
|
||||
**Symptom**: 502 Bad Gateway on API calls
|
||||
|
||||
**Check**: Backend service on 10.0.20.36
|
||||
|
||||
```powershell
|
||||
# On 10.0.20.36
|
||||
Get-Service ROA2WEB-Backend
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Server | IP | Config File | Key Pattern | Proxies To |
|
||||
|--------|----|----|-------------|------------|
|
||||
| **Public** | 10.0.20.122 | `web.config.10.0.20.122-PUBLIC` | `url="(.*)"` | `https://10.0.20.36/{R:1}` |
|
||||
| **Internal** | 10.0.20.36 | `web.config.10.0.20.36-INTERNAL` | `url="^roa2web/api/(.*)"` | `http://localhost:8000/api/{R:1}` |
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
For complete architecture details, see:
|
||||
- `deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md`
|
||||
- `DIAGNOSIS-2025-12-30.md`
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2025-12-30*
|
||||
*ROA2WEB Deployment Configuration Guide*
|
||||
@@ -124,16 +124,27 @@
|
||||
|
||||
</rules>
|
||||
|
||||
<!-- Outbound Rules (optional - for modifying responses) -->
|
||||
<!-- Outbound Rules for response headers -->
|
||||
<outboundRules>
|
||||
<!-- HSTS Header for HTTPS connections -->
|
||||
<rule name="Add HSTS Header" preCondition="IsHTTPS">
|
||||
<match serverVariable="RESPONSE_Strict-Transport-Security" pattern=".*" />
|
||||
<action type="Rewrite" value="max-age=31536000; includeSubDomains" />
|
||||
</rule>
|
||||
|
||||
<!-- API responses: NO browser/proxy caching (backend cache handles this) -->
|
||||
<rule name="No Cache for API" preCondition="IsAPIRequest">
|
||||
<match serverVariable="RESPONSE_Cache-Control" pattern=".*" />
|
||||
<action type="Rewrite" value="no-store, no-cache, must-revalidate, proxy-revalidate" />
|
||||
</rule>
|
||||
|
||||
<preConditions>
|
||||
<preCondition name="IsHTTPS">
|
||||
<add input="{HTTPS}" pattern="on" />
|
||||
</preCondition>
|
||||
<preCondition name="IsAPIRequest">
|
||||
<add input="{URL}" pattern="^/api/" />
|
||||
</preCondition>
|
||||
</preConditions>
|
||||
</outboundRules>
|
||||
</rewrite>
|
||||
|
||||
Reference in New Issue
Block a user