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
@@ -422,8 +422,8 @@ Get-Content "C:\ROA2WEB-Scripts\last-deploy.json" | ConvertFrom-Json | Format-Li
|
||||
|
||||
### Check Service Status (Server)
|
||||
```powershell
|
||||
# After deployment, verify services
|
||||
Get-Service -Name "ROA2WEB-Backend", "ROA2WEB-TelegramBot"
|
||||
# After deployment, verify service
|
||||
Get-Service -Name "ROA2WEB-Backend"
|
||||
|
||||
# Or use ROA2WEB-Console.ps1
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
@@ -669,14 +669,13 @@ Get-Content "C:\Temp\ROA2WEB-Scripts\Logs\check-and-deploy.log" -Tail 30
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Verify services are running:
|
||||
Get-Service -Name "ROA2WEB-Backend", "ROA2WEB-TelegramBot"
|
||||
# Verify service is running:
|
||||
Get-Service -Name "ROA2WEB-Backend"
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-Backend ROA2WEB Backend Service
|
||||
# Running ROA2WEB-TelegramBot ROA2WEB Telegram Bot Service
|
||||
```
|
||||
|
||||
#### Step 5: Verify Web Application
|
||||
|
||||
@@ -1,247 +0,0 @@
|
||||
# Telegram Bot Deployment Notes
|
||||
|
||||
## Overview
|
||||
|
||||
The ROA2WEB application includes an integrated Telegram bot module that runs as part of the unified FastAPI backend. This requires special configuration when deploying as a Windows service.
|
||||
|
||||
## Critical Configuration: Single Worker Only
|
||||
|
||||
### The Problem
|
||||
|
||||
**Symptom**: Telegram bot errors in logs:
|
||||
```
|
||||
telegram.error.Conflict: Conflict: terminated by other getUpdates request;
|
||||
make sure that only one bot instance is running
|
||||
```
|
||||
|
||||
**Root Cause**:
|
||||
- Uvicorn is configured to run with multiple workers (e.g., `--workers 4`)
|
||||
- Each worker process spawns its own Telegram bot instance
|
||||
- Telegram API allows **only ONE instance** per bot token to poll for updates
|
||||
- Multiple instances conflict with each other → continuous errors
|
||||
|
||||
### The Solution
|
||||
|
||||
**✅ ALWAYS use `--workers 1` for the backend service**
|
||||
|
||||
The NSSM service MUST be configured with:
|
||||
```powershell
|
||||
--workers 1
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- Single uvicorn worker = Single bot instance
|
||||
- No polling conflicts
|
||||
- Telegram bot runs cleanly
|
||||
|
||||
**Performance Impact**:
|
||||
- ✅ Minimal - the application is I/O bound (Oracle database queries), not CPU bound
|
||||
- ✅ Single worker can handle hundreds of concurrent requests with async/await
|
||||
- ✅ Connection pooling (Oracle + SQLite) ensures efficient resource usage
|
||||
|
||||
## Deployment Instructions
|
||||
|
||||
### New Installation
|
||||
|
||||
When installing with `Install-ROA2WEB.ps1`, the script now **automatically** uses `--workers 1` (as of 2025-12-29).
|
||||
|
||||
No manual configuration needed.
|
||||
|
||||
### Existing Installation (Upgrade)
|
||||
|
||||
If you have an existing installation with `--workers 4`, run the fix script:
|
||||
|
||||
```powershell
|
||||
cd C:\TEMP\ROA2WEB-Scripts
|
||||
.\Fix-TelegramWorkers.ps1
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Stop the ROA2WEB-Backend service
|
||||
2. Update NSSM parameters to `--workers 1`
|
||||
3. Restart the service
|
||||
4. Verify health and check logs for errors
|
||||
|
||||
### Manual Fix (Alternative)
|
||||
|
||||
If you prefer to fix manually:
|
||||
|
||||
```powershell
|
||||
# Stop service
|
||||
Stop-Service ROA2WEB-Backend
|
||||
|
||||
# Update NSSM parameters
|
||||
nssm set ROA2WEB-Backend AppParameters "-m uvicorn main:app --host 127.0.0.1 --port 8000 --workers 1"
|
||||
|
||||
# Verify
|
||||
nssm get ROA2WEB-Backend AppParameters
|
||||
|
||||
# Start service
|
||||
Start-Service ROA2WEB-Backend
|
||||
|
||||
# Monitor logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50 -Wait
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### 1. Check Service Parameters
|
||||
|
||||
```powershell
|
||||
nssm get ROA2WEB-Backend AppParameters
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
-m uvicorn main:app --host 127.0.0.1 --port 8000 --workers 1
|
||||
```
|
||||
|
||||
### 2. Check Logs for Bot Startup
|
||||
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
|
||||
```
|
||||
|
||||
Expected output (should appear **ONCE**, not 4 times):
|
||||
```
|
||||
22:42:39 - main - INFO - [TELEGRAM] Starting bot...
|
||||
22:42:40 - main - INFO - [TELEGRAM] ✅ Bot running: @ROA2WEBBot
|
||||
```
|
||||
|
||||
### 3. Verify No Conflict Errors
|
||||
|
||||
After waiting 1-2 minutes, check logs again:
|
||||
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 100 | Select-String "Conflict"
|
||||
```
|
||||
|
||||
Expected output: **No results** (no conflict errors)
|
||||
|
||||
### 4. Check Process Count
|
||||
|
||||
```powershell
|
||||
Get-Process -Name python | Where-Object { $_.MainWindowTitle -eq "" }
|
||||
```
|
||||
|
||||
You should see:
|
||||
- **1 parent process** (uvicorn master)
|
||||
- **1 child process** (the single worker)
|
||||
- **Total: 2 python processes**
|
||||
|
||||
With `--workers 4`, you would see 5 processes (1 parent + 4 workers) ❌
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Still seeing conflict errors after fix?
|
||||
|
||||
1. **Verify service parameters**:
|
||||
```powershell
|
||||
nssm get ROA2WEB-Backend AppParameters
|
||||
```
|
||||
Should show `--workers 1`
|
||||
|
||||
2. **Fully restart the service**:
|
||||
```powershell
|
||||
Stop-Service ROA2WEB-Backend -Force
|
||||
Start-Sleep -Seconds 5
|
||||
Start-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
3. **Check for old processes**:
|
||||
```powershell
|
||||
Get-Process python | Stop-Process -Force
|
||||
Start-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
### Service won't start after change?
|
||||
|
||||
1. **Check logs** for the actual error:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
|
||||
```
|
||||
|
||||
2. **Common issues**:
|
||||
- Oracle connection timeout → Check SSH tunnel or Oracle listener
|
||||
- Module import errors → Verify PYTHONPATH in NSSM config
|
||||
- Port already in use → Kill process using port 8000
|
||||
|
||||
### Cache stats endpoint (502 error)
|
||||
|
||||
The `/api/reports/cache/stats` endpoint may return 502 Bad Gateway with multiple workers because:
|
||||
- Multiple workers try to access the same SQLite cache database file
|
||||
- SQLite locking conflicts cause worker crashes
|
||||
- **Resolved by using `--workers 1`** ✅
|
||||
|
||||
## Related Issues
|
||||
|
||||
### Pydantic v2 Warnings
|
||||
|
||||
**Warning**:
|
||||
```
|
||||
UserWarning: Valid config keys have changed in V2:
|
||||
* 'schema_extra' has been renamed to 'json_schema_extra'
|
||||
```
|
||||
|
||||
**Fix**: Updated in `backend/modules/reports/models/trial_balance.py` (2025-12-29)
|
||||
|
||||
**Not critical** - just warnings, doesn't affect functionality.
|
||||
|
||||
### PTB Handler Warning
|
||||
|
||||
**Warning**:
|
||||
```
|
||||
PTBUserWarning: If 'per_message=False', 'CallbackQueryHandler' will not be tracked for every message.
|
||||
```
|
||||
|
||||
**Location**: `backend/modules/telegram/bot/email_handlers.py:742`
|
||||
|
||||
**Impact**: Informational warning, bot works correctly
|
||||
|
||||
**Fix**: Add `per_message=True` to ConversationHandler (optional enhancement)
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
### Why Not Multiple Workers?
|
||||
|
||||
**Question**: Why not run the Telegram bot in a separate process/service?
|
||||
|
||||
**Answer**: Possible, but current architecture is simpler:
|
||||
|
||||
**Current (Recommended)**:
|
||||
- ✅ Single service manages everything
|
||||
- ✅ Unified logging and monitoring
|
||||
- ✅ Simpler deployment
|
||||
- ✅ Single process to debug
|
||||
- ⚠️ Must use `--workers 1`
|
||||
|
||||
**Alternative (Separate Bot Service)**:
|
||||
- ✅ Could use `--workers 4` for web backend
|
||||
- ❌ Requires two Windows services
|
||||
- ❌ More complex deployment
|
||||
- ❌ Two processes to monitor
|
||||
- ❌ Coordination required
|
||||
|
||||
**Decision**: Keep integrated bot with single worker. Performance is excellent for our use case.
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
With `--workers 1`:
|
||||
- **Concurrent requests**: Handled via async/await (100+ concurrent)
|
||||
- **Database pooling**: 5-10 connections in Oracle pool (shared)
|
||||
- **Memory usage**: ~300-500 MB per worker
|
||||
- **CPU usage**: Low (I/O bound, not CPU bound)
|
||||
- **Response times**: 50-200ms (mostly database query time)
|
||||
|
||||
Performance is **more than adequate** for:
|
||||
- 50-100 concurrent users
|
||||
- 1000+ requests per minute
|
||||
- Multiple modules (Reports, Data Entry, Telegram)
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Always deploy ROA2WEB backend with `--workers 1` to avoid Telegram bot conflicts.**
|
||||
|
||||
The fix script (`Fix-TelegramWorkers.ps1`) makes this change automatically for existing installations.
|
||||
|
||||
New installations (Install-ROA2WEB.ps1) are pre-configured correctly.
|
||||
@@ -1,855 +0,0 @@
|
||||
# ROA2WEB Telegram Bot - Windows Server Deployment Guide
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This documentation refers to the OLD microservices architecture where the Telegram bot
|
||||
> ran as a separate service on port 8002. The current architecture is an **ultrathin monolith**
|
||||
> where everything runs on a single port (8000/8001) via `backend/main.py`.
|
||||
>
|
||||
> **Current Architecture**: Telegram bot runs as a background task within the unified backend.
|
||||
> Internal API endpoints are now at `/api/telegram/internal/*` on the main port.
|
||||
>
|
||||
> See `CLAUDE.md` and `QUICK-START.md` for the current architecture.
|
||||
|
||||
**Target Server**: Windows Server (10.0.20.36)
|
||||
**Deployment Method**: Windows Service (NSSM) - No Docker
|
||||
**Service Name**: ROA2WEB-TelegramBot
|
||||
**Internal API Port**: ~~8002~~ (DEPRECATED - now via main backend)
|
||||
**Created**: 2025-10-22
|
||||
**Last Updated**: 2025-10-22
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Prerequisites](#prerequisites)
|
||||
3. [Deployment Architecture](#deployment-architecture)
|
||||
4. [Installation Steps](#installation-steps)
|
||||
5. [Configuration](#configuration)
|
||||
6. [Service Management](#service-management)
|
||||
7. [Database Backup](#database-backup)
|
||||
8. [Monitoring & Troubleshooting](#monitoring--troubleshooting)
|
||||
9. [Security Considerations](#security-considerations)
|
||||
10. [Maintenance Procedures](#maintenance-procedures)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The ROA2WEB Telegram Bot is deployed as a Windows Service on the same server as the backend (10.0.20.36). It provides an alternative conversational interface to ROA2WEB using Claude Agent SDK.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Conversational AI**: Claude Agent SDK with 5 custom tools
|
||||
- **Account Linking**: Secure linking between Telegram and Oracle accounts
|
||||
- **Real-time Queries**: Dashboard, invoices, treasury, exports
|
||||
- **Database**: Standalone SQLite for Telegram-specific data
|
||||
- **Internal API**: FastAPI endpoint for backend callbacks (port 8002)
|
||||
- **Production Ready**: All components use real backend integration (no mocks)
|
||||
|
||||
### Deployment Method
|
||||
|
||||
- **Windows Service**: Runs via NSSM (Non-Sucking Service Manager)
|
||||
- **No Docker**: Direct Windows deployment (same pattern as backend)
|
||||
- **Auto-start**: Service starts automatically on server boot
|
||||
- **Auto-recovery**: Service restarts automatically on failure
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Server Requirements
|
||||
|
||||
- **Operating System**: Windows Server 2016+ or Windows 10/11
|
||||
- **Python**: 3.11 or higher
|
||||
- **RAM**: Minimum 512 MB (dedicated to service)
|
||||
- **Disk Space**: Minimum 500 MB
|
||||
- **Network**: Access to localhost:8000 (backend API)
|
||||
|
||||
### Required Credentials
|
||||
|
||||
1. **Telegram Bot Token**
|
||||
- Get from @BotFather on Telegram
|
||||
- Command: `/newbot` or `/mybots`
|
||||
- Example: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`
|
||||
|
||||
2. **Claude Authentication** (Choose ONE method)
|
||||
|
||||
**Method A: Claude Pro/Max Subscription** ⭐ **RECOMMENDED**
|
||||
- ✅ **NO API key needed**
|
||||
- ✅ **NO additional costs** (included in your subscription)
|
||||
- ✅ Uses browser authentication
|
||||
- See: [Claude Authentication Setup](#claude-authentication-setup) below
|
||||
|
||||
**Method B: Claude API Key** (Alternative)
|
||||
- Get from Anthropic Console: https://console.anthropic.com/settings/keys
|
||||
- Example: `sk-ant-api03-XXXXXXXX...`
|
||||
- ⚠️ Usage-based billing applies
|
||||
- Takes precedence over Method A if both are configured
|
||||
|
||||
3. **Backend Access**
|
||||
- Backend should be running on http://localhost:8000
|
||||
- Verify: `Invoke-WebRequest http://localhost:8000/health`
|
||||
|
||||
### Software Prerequisites
|
||||
|
||||
- **PowerShell 5.1+**: Built into Windows Server
|
||||
- **Python 3.11+**: Will be installed if missing (via Chocolatey)
|
||||
- **NSSM**: Will be installed automatically by installation script
|
||||
|
||||
---
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
C:\inetpub\wwwroot\roa2web\telegram-bot\
|
||||
├── app\ # Application source code
|
||||
│ ├── main.py # Entry point, Claude Agent wrapper
|
||||
│ ├── bot\ # Telegram bot handlers
|
||||
│ ├── agent\ # Claude Agent tools and sessions
|
||||
│ ├── auth\ # Account linking logic
|
||||
│ ├── db\ # SQLite database operations
|
||||
│ ├── api\ # Backend API client
|
||||
│ └── internal_api.py # FastAPI internal API
|
||||
├── venv\ # Python virtual environment
|
||||
├── data\ # SQLite database
|
||||
│ └── telegram_bot.db # Main database file
|
||||
├── logs\ # Application logs
|
||||
│ ├── stdout.log # Service output
|
||||
│ ├── stderr.log # Service errors
|
||||
│ └── backup.log # Backup operations
|
||||
├── backups\ # Database backups
|
||||
├── temp\ # Temporary files
|
||||
├── scripts\ # PowerShell management scripts
|
||||
├── config\ # Configuration templates
|
||||
├── requirements.txt # Python dependencies
|
||||
└── .env # Environment configuration
|
||||
```
|
||||
|
||||
### Service Integration
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Windows Server 10.0.20.36 │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ IIS (Port 80) │ │ ROA2WEB-Backend │ │
|
||||
│ │ Frontend Static │ │ (Port 8000) │ │
|
||||
│ └──────────────────┘ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ │ HTTP API Calls │
|
||||
│ │ │
|
||||
│ ┌─────────────────▼──────────────┐ │
|
||||
│ │ ROA2WEB-TelegramBot │ │
|
||||
│ │ (Port 8002 - Internal API) │ │
|
||||
│ │ - Telegram Bot Handlers │ │
|
||||
│ │ - Claude Agent SDK │ │
|
||||
│ │ - SQLite Database │ │
|
||||
│ └────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Telegram Bot API
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Telegram │
|
||||
│ Cloud │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### Step 1: Build Deployment Package (Development Machine)
|
||||
|
||||
On your development machine (WSL/Linux), run:
|
||||
|
||||
```bash
|
||||
cd /mnt/e/proiecte/roa2web/roa2web/deployment/windows/scripts
|
||||
./Build-TelegramBot.ps1
|
||||
```
|
||||
|
||||
This creates the deployment package at:
|
||||
```
|
||||
../deploy-package/telegram-bot/
|
||||
```
|
||||
|
||||
**Package Contents**:
|
||||
- `app/` - Application source code
|
||||
- `requirements.txt` - Python dependencies
|
||||
- `.env.example` - Configuration template
|
||||
- `scripts/` - PowerShell management scripts
|
||||
- `config/` - Production config templates
|
||||
- `README.txt` - Deployment instructions
|
||||
|
||||
### Step 2: Transfer Package to Server
|
||||
|
||||
**Option A: Network Share** (Recommended)
|
||||
```powershell
|
||||
# On development machine
|
||||
Copy-Item -Path ./deploy-package/telegram-bot -Destination \\10.0.20.36\C$\Temp\telegram-bot-deploy -Recurse
|
||||
```
|
||||
|
||||
**Option B: RDP**
|
||||
1. Connect to server via RDP: `mstsc /v:10.0.20.36`
|
||||
2. Manually copy deployment package to `C:\Temp\telegram-bot-deploy`
|
||||
|
||||
### Step 3: Run Installation Script
|
||||
|
||||
On Windows Server (10.0.20.36), open PowerShell as Administrator:
|
||||
|
||||
```powershell
|
||||
cd C:\Temp\telegram-bot-deploy\scripts
|
||||
.\Install-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Installation Process**:
|
||||
1. ✅ Checks Python 3.11+ installation
|
||||
2. ✅ Installs NSSM (service manager)
|
||||
3. ✅ Creates directory structure
|
||||
4. ✅ Creates Python virtual environment
|
||||
5. ✅ Installs Python dependencies
|
||||
6. ✅ Creates Windows Service (ROA2WEB-TelegramBot)
|
||||
7. ✅ Creates .env configuration template
|
||||
|
||||
**Installation Output**:
|
||||
```
|
||||
====================================================================
|
||||
ROA2WEB TELEGRAM BOT INSTALLATION COMPLETED
|
||||
====================================================================
|
||||
|
||||
Installation Details:
|
||||
Install Path: C:\inetpub\wwwroot\roa2web\telegram-bot
|
||||
Service Name: ROA2WEB-TelegramBot
|
||||
Internal API Port: 8002
|
||||
|
||||
Next Steps:
|
||||
1. Edit configuration: C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
2. Start service: .\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Step 4: Configure Environment
|
||||
|
||||
Edit the `.env` file:
|
||||
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
```
|
||||
|
||||
**Required Configuration**:
|
||||
```env
|
||||
# CRITICAL: Update this value
|
||||
TELEGRAM_BOT_TOKEN=your_production_bot_token_from_@BotFather
|
||||
|
||||
# Claude Authentication: Leave empty to use Claude Pro/Max subscription
|
||||
CLAUDE_API_KEY=
|
||||
|
||||
# Verify these are correct
|
||||
BACKEND_URL=http://localhost:8000
|
||||
SQLITE_DB_PATH=C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
LOG_LEVEL=INFO
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
**Get Bot Token**:
|
||||
1. Open Telegram, search for `@BotFather`
|
||||
2. Send `/newbot` or `/mybots`
|
||||
3. Copy token to `TELEGRAM_BOT_TOKEN`
|
||||
|
||||
### Step 4a: Claude Authentication Setup
|
||||
|
||||
**Choose ONE authentication method:**
|
||||
|
||||
#### **Method A: Claude Pro/Max Subscription** ⭐ **RECOMMENDED**
|
||||
|
||||
If you have a Claude Pro or Claude Max subscription, use this method (NO API key needed!):
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-ClaudeAuth.ps1
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Script installs `claude-code` CLI (if not already installed)
|
||||
2. Opens your browser for authentication
|
||||
3. Log in with your Claude Pro/Max account
|
||||
4. Authorize the application
|
||||
5. Credentials are saved to: `%APPDATA%\claude\credentials.json`
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
====================================================================
|
||||
IMPORTANT: Browser Authentication Required
|
||||
====================================================================
|
||||
|
||||
1. A browser window will open
|
||||
2. Log in with your Claude Pro/Max account
|
||||
3. Authorize the application
|
||||
4. Return to this window after authentication
|
||||
|
||||
====================================================================
|
||||
|
||||
[*] Opening browser for authentication...
|
||||
[OK] Authentication successful!
|
||||
[OK] Credentials file found and valid
|
||||
[OK] .env will use Claude Pro subscription (browser login)
|
||||
|
||||
====================================================================
|
||||
CLAUDE AUTHENTICATION SETUP COMPLETE
|
||||
====================================================================
|
||||
```
|
||||
|
||||
**Alternative: Copy credentials from development machine**
|
||||
|
||||
If the server doesn't have browser access, authenticate on your local machine and copy credentials:
|
||||
|
||||
```powershell
|
||||
# On local machine (with browser):
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
claude-code login
|
||||
|
||||
# Copy credentials file to server
|
||||
Copy-Item "$env:APPDATA\claude\credentials.json" -Destination "\\10.0.20.36\C$\Temp\claude-credentials.json"
|
||||
|
||||
# On server:
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-ClaudeAuth.ps1 -Method copy -CredentialsPath "C:\Temp\claude-credentials.json"
|
||||
```
|
||||
|
||||
#### **Method B: Claude API Key** (Alternative)
|
||||
|
||||
If you prefer to use an API key instead:
|
||||
|
||||
1. Visit https://console.anthropic.com/settings/keys
|
||||
2. Create new key
|
||||
3. Edit `.env` and set `CLAUDE_API_KEY=sk-ant-api03-XXXXXXXX...`
|
||||
4. ⚠️ Usage-based billing applies
|
||||
|
||||
**Note:** API key takes precedence over browser login if both are configured.
|
||||
|
||||
### Step 5: Start Service
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
[*] Starting ROA2WEB Telegram Bot Service...
|
||||
[*] Service start command issued
|
||||
[*] Waiting for service to start... (5/30)
|
||||
[OK] Service started successfully
|
||||
[OK] Health check passed: healthy
|
||||
[OK] Database: connected
|
||||
```
|
||||
|
||||
### Step 6: Verify Installation
|
||||
|
||||
**Check Service Status**:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
```
|
||||
|
||||
Expected: `Status = Running`
|
||||
|
||||
**Check Health Endpoint**:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health | ConvertFrom-Json
|
||||
```
|
||||
|
||||
Expected Output:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2025-10-22T14:30:00",
|
||||
"database": {
|
||||
"status": "connected",
|
||||
"users": 0,
|
||||
"pending_codes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test Bot on Telegram**:
|
||||
1. Open Telegram
|
||||
2. Search for your bot (name from @BotFather)
|
||||
3. Send `/start`
|
||||
4. Expected: Welcome message with linking instructions
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables Reference
|
||||
|
||||
See `.env.production.windows.telegram` in `config/` directory for complete reference.
|
||||
|
||||
**Key Settings**:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `TELEGRAM_BOT_TOKEN` | *required* | Bot token from @BotFather |
|
||||
| `CLAUDE_API_KEY` | *required* | API key from Anthropic |
|
||||
| `BACKEND_URL` | `http://localhost:8000` | Backend API URL |
|
||||
| `SQLITE_DB_PATH` | `C:\...\telegram_bot.db` | Database file location |
|
||||
| `INTERNAL_API_PORT` | `8002` | Internal API port |
|
||||
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG/INFO/WARN/ERROR) |
|
||||
| `ENVIRONMENT` | `production` | Environment name |
|
||||
| `AUTH_CODE_EXPIRY_MINUTES` | `15` | Linking code expiry time |
|
||||
| `SESSION_TIMEOUT_MINUTES` | `60` | User session timeout |
|
||||
| `MAX_CONVERSATION_HISTORY` | `20` | Max messages per session |
|
||||
|
||||
### Applying Configuration Changes
|
||||
|
||||
After editing `.env`:
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Management
|
||||
|
||||
### Start Service
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Stop Service
|
||||
|
||||
```powershell
|
||||
.\Stop-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Restart Service
|
||||
|
||||
```powershell
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Detailed info
|
||||
Get-Service ROA2WEB-TelegramBot | Select-Object *
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
**Real-time Logs** (tail -f equivalent):
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50 -Wait
|
||||
```
|
||||
|
||||
**Error Logs**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
```
|
||||
|
||||
**Backup Logs**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\backup.log -Tail 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Backup
|
||||
|
||||
### Manual Backup
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Backup-TelegramDB.ps1
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- Backup file: `backups/telegram_bot_backup_YYYYMMDD-HHMMSS.db.zip`
|
||||
- Compressed and timestamped
|
||||
- Integrity tested automatically
|
||||
|
||||
### Setup Automated Daily Backup
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-DailyBackup.ps1
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Runs daily at 2:00 AM
|
||||
- Keeps last 30 days of backups
|
||||
- Runs as SYSTEM account
|
||||
- Logs all operations
|
||||
|
||||
**Verify Scheduled Task**:
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"
|
||||
```
|
||||
|
||||
**Run Backup Manually** (via Task Scheduler):
|
||||
```powershell
|
||||
Start-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"
|
||||
```
|
||||
|
||||
### Restore from Backup
|
||||
|
||||
1. Stop service:
|
||||
```powershell
|
||||
.\Stop-TelegramBot.ps1
|
||||
```
|
||||
|
||||
2. Find backup file:
|
||||
```powershell
|
||||
Get-ChildItem C:\inetpub\wwwroot\roa2web\telegram-bot\backups | Sort-Object LastWriteTime -Descending
|
||||
```
|
||||
|
||||
3. Extract backup (if compressed):
|
||||
```powershell
|
||||
Expand-Archive -Path "backups\telegram_bot_backup_YYYYMMDD-HHMMSS.db.zip" -DestinationPath "temp\"
|
||||
```
|
||||
|
||||
4. Replace database:
|
||||
```powershell
|
||||
Copy-Item -Path "temp\telegram_bot_backup_YYYYMMDD-HHMMSS.db" -Destination "data\telegram_bot.db" -Force
|
||||
```
|
||||
|
||||
5. Start service:
|
||||
```powershell
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Troubleshooting
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Service Health**:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot | Select-Object Name, Status, StartType
|
||||
```
|
||||
|
||||
**API Health**:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
**Database Stats**:
|
||||
```powershell
|
||||
(Invoke-WebRequest http://localhost:8002/internal/stats).Content | ConvertFrom-Json
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Service Won't Start
|
||||
|
||||
**Symptoms**: Service shows "Stopped" or "Starting" forever
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Missing .env file** → Create from `.env.example`
|
||||
2. **Invalid bot token** → Check `TELEGRAM_BOT_TOKEN`
|
||||
3. **Invalid Claude API key** → Check `CLAUDE_API_KEY`
|
||||
4. **Port 8002 already in use** → Change `INTERNAL_API_PORT`
|
||||
5. **Backend not running** → Start ROA2WEB-Backend service
|
||||
|
||||
**Solutions**:
|
||||
```powershell
|
||||
# Fix config
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Check port availability
|
||||
Get-NetTCPConnection -LocalPort 8002
|
||||
|
||||
# Restart service
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Bot Not Responding on Telegram
|
||||
|
||||
**Symptoms**: Bot doesn't reply to messages
|
||||
|
||||
**Diagnosis**:
|
||||
1. Check service status:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
```
|
||||
2. Check health endpoint:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
```
|
||||
3. Check logs for errors:
|
||||
```powershell
|
||||
Get-Content logs\stderr.log -Tail 50
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Service stopped** → Start service
|
||||
2. **Invalid bot token** → Update `.env`
|
||||
3. **Network issues** → Check internet connectivity
|
||||
4. **Bot blocked by user** → User must /start bot again
|
||||
|
||||
#### Account Linking Fails
|
||||
|
||||
**Symptoms**: `/link CODE` returns error
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
# Check internal API
|
||||
Invoke-WebRequest http://localhost:8002/internal/stats
|
||||
|
||||
# Check backend connectivity
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Code expired** (15 min) → Generate new code
|
||||
2. **Backend unreachable** → Check ROA2WEB-Backend service
|
||||
3. **Database error** → Check SQLite file permissions
|
||||
|
||||
#### Database Errors
|
||||
|
||||
**Symptoms**: "Database locked" or "Cannot open database"
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
# Check database file
|
||||
Test-Path C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
|
||||
# Check file permissions
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
```powershell
|
||||
# Stop service
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Fix permissions
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\data /grant "SYSTEM:(OI)(CI)F" /T
|
||||
|
||||
# Restart service
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Secrets Management
|
||||
|
||||
**NEVER**:
|
||||
- Commit `.env` to git
|
||||
- Share bot token or API keys
|
||||
- Log sensitive data
|
||||
|
||||
**ALWAYS**:
|
||||
- Keep backups of `.env` in secure location
|
||||
- Rotate API keys periodically
|
||||
- Use strong file permissions
|
||||
|
||||
**File Permissions**:
|
||||
```powershell
|
||||
# Restrict .env to SYSTEM and Administrators only
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\.env /grant "SYSTEM:F" /grant "Administrators:F" /inheritance:r
|
||||
```
|
||||
|
||||
### Network Security
|
||||
|
||||
- **Internal API (8002)**: Bind to 127.0.0.1 (localhost only)
|
||||
- **Backend API (8000)**: Already on localhost
|
||||
- **No Firewall Rules Needed**: All communication is local
|
||||
|
||||
### Bot Security
|
||||
|
||||
- **Account Linking**: 8-character codes, 15-minute expiry
|
||||
- **JWT Tokens**: Signed and verified by backend
|
||||
- **Rate Limiting**: Built into authentication middleware
|
||||
- **Session Timeout**: 60 minutes of inactivity
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Procedures
|
||||
|
||||
### Updates and Deployments
|
||||
|
||||
1. **Build new deployment package** (dev machine):
|
||||
```bash
|
||||
./Build-TelegramBot.ps1
|
||||
```
|
||||
|
||||
2. **Transfer to server**:
|
||||
```powershell
|
||||
Copy-Item -Path ./deploy-package/telegram-bot -Destination \\10.0.20.36\C$\Temp\telegram-bot-update -Recurse
|
||||
```
|
||||
|
||||
3. **Deploy update** (server):
|
||||
```powershell
|
||||
cd C:\Temp\telegram-bot-update\scripts
|
||||
.\Deploy-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Deployment Features**:
|
||||
- ✅ Automatic backup before deployment
|
||||
- ✅ Stops service, updates files, restarts service
|
||||
- ✅ Preserves `.env` configuration
|
||||
- ✅ Automatic rollback on failure
|
||||
- ✅ Health check after deployment
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Logs are automatically rotated by Python logging:
|
||||
- **Max size**: 10 MB per file
|
||||
- **Backups**: 5 old log files kept
|
||||
- **Location**: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\`
|
||||
|
||||
**Manual cleanup**:
|
||||
```powershell
|
||||
# Delete old logs (older than 30 days)
|
||||
Get-ChildItem C:\inetpub\wwwroot\roa2web\telegram-bot\logs\*.log |
|
||||
Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
|
||||
Remove-Item -Force
|
||||
```
|
||||
|
||||
### Database Maintenance
|
||||
|
||||
**Cleanup expired data** (automatic via scheduled task):
|
||||
- Expired auth codes (older than 15 minutes)
|
||||
- Old sessions (inactive for 60+ minutes)
|
||||
- Runs hourly automatically
|
||||
|
||||
**Manual cleanup**:
|
||||
```sql
|
||||
-- Connect to database
|
||||
sqlite3 C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
|
||||
-- Delete expired codes
|
||||
DELETE FROM telegram_auth_codes WHERE created_at < datetime('now', '-15 minutes');
|
||||
|
||||
-- Delete old sessions
|
||||
DELETE FROM telegram_sessions WHERE updated_at < datetime('now', '-60 minutes');
|
||||
```
|
||||
|
||||
### Service Health Monitoring
|
||||
|
||||
**Daily Checks** (manual or script):
|
||||
```powershell
|
||||
# Service status
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Health endpoint
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Check logs for errors
|
||||
Get-Content logs\stderr.log -Tail 50 | Select-String "ERROR"
|
||||
|
||||
# Check database size
|
||||
(Get-Item data\telegram_bot.db).Length / 1MB
|
||||
```
|
||||
|
||||
**Weekly Checks**:
|
||||
- Review backup logs
|
||||
- Check backup retention (30 days)
|
||||
- Review disk space usage
|
||||
- Check for Windows updates
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### PowerShell Scripts Reference
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `Install-TelegramBot.ps1` | Initial installation |
|
||||
| `Deploy-TelegramBot.ps1` | Deploy updates |
|
||||
| `Build-TelegramBot.ps1` | Build deployment package |
|
||||
| `Start-TelegramBot.ps1` | Start service |
|
||||
| `Stop-TelegramBot.ps1` | Stop service |
|
||||
| `Restart-TelegramBot.ps1` | Restart service |
|
||||
| `Backup-TelegramDB.ps1` | Manual database backup |
|
||||
| `Setup-DailyBackup.ps1` | Configure automated backups |
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/internal/health` | GET | Health check |
|
||||
| `/internal/stats` | GET | Database statistics |
|
||||
| `/internal/save-code` | POST | Save auth code (from backend) |
|
||||
| `/internal/verify-code` | POST | Verify auth code |
|
||||
|
||||
### Database Schema
|
||||
|
||||
**telegram_users**:
|
||||
```sql
|
||||
CREATE TABLE telegram_users (
|
||||
telegram_user_id INTEGER PRIMARY KEY,
|
||||
oracle_user_id INTEGER NOT NULL,
|
||||
oracle_username TEXT NOT NULL,
|
||||
jwt_token TEXT NOT NULL,
|
||||
jwt_refresh_token TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
**telegram_auth_codes**:
|
||||
```sql
|
||||
CREATE TABLE telegram_auth_codes (
|
||||
code TEXT PRIMARY KEY,
|
||||
oracle_user_id INTEGER NOT NULL,
|
||||
oracle_username TEXT NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
expires_at TIMESTAMP NOT NULL,
|
||||
used INTEGER DEFAULT 0
|
||||
);
|
||||
```
|
||||
|
||||
**telegram_sessions**:
|
||||
```sql
|
||||
CREATE TABLE telegram_sessions (
|
||||
telegram_user_id INTEGER PRIMARY KEY,
|
||||
conversation_history TEXT, -- JSON
|
||||
session_data TEXT, -- JSON
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
**Documentation**:
|
||||
- Project README: `/mnt/e/proiecte/roa2web/roa2web/backend/modules/telegram/README.md`
|
||||
- Progress Tracker: `/mnt/e/proiecte/roa2web/roa2web/development/TELEGRAM_BOT_PROGRESS.md`
|
||||
- Production Deployment Plan: `/mnt/e/proiecte/roa2web/roa2web/development/TELEGRAM_BOT_PRODUCTION_DEPLOYMENT.md`
|
||||
|
||||
**Logs Location**:
|
||||
- Service Output: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log`
|
||||
- Service Errors: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log`
|
||||
- Backups: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\backup.log`
|
||||
|
||||
**Contact**: ROA2WEB Development Team
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: 2025-10-22
|
||||
**Status**: Production Ready
|
||||
@@ -1,546 +0,0 @@
|
||||
# ROA2WEB Telegram Bot - Windows Deployment Troubleshooting Guide
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This documentation refers to the OLD microservices architecture (port 8002).
|
||||
> The current architecture is an **ultrathin monolith** - everything on port 8000/8001.
|
||||
> Telegram internal API is now at `/api/telegram/internal/*` on the main backend.
|
||||
|
||||
This guide helps diagnose and fix common issues with Telegram bot integration on Windows Server deployments.
|
||||
|
||||
## Problem: "Link invalid sau expirat" (Invalid or expired link)
|
||||
|
||||
When users generate a linking code in the web frontend but the Telegram bot says the code is invalid or expired, this indicates a communication problem between the backend and telegram bot services.
|
||||
|
||||
### Root Cause
|
||||
|
||||
The backend cannot communicate with the Telegram bot's internal API to save the generated linking codes.
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
Run these PowerShell commands on the Windows Server (10.0.20.36) to diagnose:
|
||||
|
||||
#### 1. Check Telegram Bot Service Status
|
||||
|
||||
```powershell
|
||||
# Check if service is running
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-TelegramBot ROA2WEB Telegram Bot Service
|
||||
```
|
||||
|
||||
If service is **not running**, start it:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 2. Check Internal API Port (8002)
|
||||
|
||||
```powershell
|
||||
# Check if port 8002 is listening
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Expected output (should show LISTENING):
|
||||
# TCP 127.0.0.1:8002 0.0.0.0:0 LISTENING <PID>
|
||||
```
|
||||
|
||||
If port is **not listening**, the telegram bot service may not have started correctly. Check logs:
|
||||
```powershell
|
||||
# View service logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50
|
||||
|
||||
# View error logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50
|
||||
```
|
||||
|
||||
#### 3. Test Internal API Health Endpoint
|
||||
|
||||
```powershell
|
||||
# Test if internal API responds
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Expected output:
|
||||
# StatusCode : 200
|
||||
# StatusDescription : OK
|
||||
# Content : {"status":"healthy","timestamp":"2025-...","database_stats":{...}}
|
||||
```
|
||||
|
||||
If this **fails**, the internal API is not running. Check telegram bot service logs.
|
||||
|
||||
#### 4. Check Backend .env Configuration
|
||||
|
||||
```powershell
|
||||
# View backend .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Look for this line:
|
||||
# TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
If the line is **missing or incorrect**, add/fix it:
|
||||
```
|
||||
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
Then restart backend service:
|
||||
```powershell
|
||||
Restart-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
#### 5. Check Telegram Bot .env Configuration
|
||||
|
||||
```powershell
|
||||
# View telegram bot .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Verify these settings:
|
||||
# TELEGRAM_BOT_TOKEN=<your_production_bot_token>
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
# INTERNAL_API_PORT=8002
|
||||
# INTERNAL_API_HOST=127.0.0.1
|
||||
```
|
||||
|
||||
If TELEGRAM_BOT_TOKEN is wrong (e.g., still using DEV token), update it and restart:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 6. Test Full Linking Flow
|
||||
|
||||
```powershell
|
||||
# 1. Test backend can reach telegram bot internal API
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
|
||||
|
||||
# Expected output:
|
||||
# StatusCode: 201 (Created)
|
||||
# Content: {"success":true,"code":"TEST1234","expires_at":"...","message":"..."}
|
||||
|
||||
# 2. Verify code was saved
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234"}'
|
||||
|
||||
# Expected output:
|
||||
# StatusCode: 200 (OK)
|
||||
# Content: {"valid":true,"oracle_username":"testuser","message":"Code is valid"}
|
||||
```
|
||||
|
||||
If step 1 **fails**, there's a network/firewall issue blocking localhost:8002.
|
||||
|
||||
### Solution Checklist
|
||||
|
||||
Fix the issue by following this checklist in order:
|
||||
|
||||
- [ ] **Telegram bot service is running**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
# If stopped: cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts; .\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
- [ ] **Internal API port 8002 is listening**
|
||||
```powershell
|
||||
netstat -ano | findstr :8002
|
||||
# Should show LISTENING on 127.0.0.1:8002
|
||||
```
|
||||
|
||||
- [ ] **Internal API responds to health checks**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
# Should return 200 OK with status "healthy"
|
||||
```
|
||||
|
||||
- [ ] **Backend .env has TELEGRAM_BOT_INTERNAL_API configured**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
# Add: TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
- [ ] **Backend service restarted after .env changes**
|
||||
```powershell
|
||||
Restart-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot .env has correct TELEGRAM_BOT_TOKEN**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
# Should have ROA2WEBBot token, not ROA2WEBDEVBot token
|
||||
```
|
||||
|
||||
- [ ] **Test full linking flow from web frontend**
|
||||
- Log in to web frontend (http://10.0.20.36)
|
||||
- Generate linking code
|
||||
- Send code to @ROA2WEBBot via `/start CODE12345`
|
||||
- Should receive success message from bot
|
||||
|
||||
---
|
||||
|
||||
## Problem: "Cannot connect to backend" / Connection Errors
|
||||
|
||||
After successfully generating a linking code, the Telegram bot finds the code but fails to complete the linking with error messages like:
|
||||
|
||||
- `httpcore.ConnectError: All connection attempts failed`
|
||||
- `Cannot connect to backend at http://localhost:8000`
|
||||
- `AttributeError: 'ConnectError' object has no attribute 'response'` (fixed in latest version)
|
||||
|
||||
### Root Cause
|
||||
|
||||
The Telegram bot cannot communicate with the FastAPI backend to verify the Oracle user and obtain a JWT token. This happens when:
|
||||
|
||||
1. Backend service is not running
|
||||
2. Backend is running on wrong port
|
||||
3. BACKEND_URL in telegram bot .env is incorrect
|
||||
4. Firewall blocking communication
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
#### 1. Check Backend Service Status
|
||||
|
||||
```powershell
|
||||
# Check if backend service is running
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-Backend ROA2WEB Backend Service
|
||||
```
|
||||
|
||||
If service is **not running**, start it:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
.\Start-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
#### 2. Check Backend Port (8000)
|
||||
|
||||
```powershell
|
||||
# Check if port 8000 is listening
|
||||
netstat -ano | findstr :8000
|
||||
|
||||
# Expected output (should show LISTENING):
|
||||
# TCP 0.0.0.0:8000 0.0.0.0:0 LISTENING <PID>
|
||||
```
|
||||
|
||||
If port is **not listening**, check backend logs:
|
||||
```powershell
|
||||
# View backend service logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
|
||||
```
|
||||
|
||||
#### 3. Test Backend Health Endpoint
|
||||
|
||||
```powershell
|
||||
# Test if backend API responds
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
|
||||
# Expected output:
|
||||
# StatusCode : 200
|
||||
# Content : {"status":"healthy",...}
|
||||
```
|
||||
|
||||
If this **fails**, backend is not accessible. Check service logs.
|
||||
|
||||
#### 4. Check Telegram Bot BACKEND_URL Configuration
|
||||
|
||||
```powershell
|
||||
# View telegram bot .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Verify this line exists and is correct:
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
**Common mistakes:**
|
||||
- Using `http://localhost:8001` (dev port instead of production port 8000)
|
||||
- Missing `http://` prefix
|
||||
- Using IP address instead of localhost
|
||||
|
||||
If BACKEND_URL is **incorrect**, fix it and restart:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 5. Test Backend Verify-User Endpoint
|
||||
|
||||
```powershell
|
||||
# Test the specific endpoint telegram bot uses
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8000/api/telegram/auth/verify-user `
|
||||
-Headers @{"Content-Type"="application/json"} `
|
||||
-Body '{"linking_code":"TESTCODE","oracle_username":"testuser"}'
|
||||
|
||||
# Expected output (will fail with 400/404 for test data, but confirms endpoint is reachable):
|
||||
# StatusCode: 400 or 404 (NOT connection error)
|
||||
```
|
||||
|
||||
If you get **connection error** instead of 400/404, backend is not running or port is wrong.
|
||||
|
||||
### Solution Checklist
|
||||
|
||||
Fix the issue by following this checklist:
|
||||
|
||||
- [ ] **Backend service is running**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-Backend
|
||||
# If stopped: cd C:\inetpub\wwwroot\roa2web\scripts; .\Start-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
- [ ] **Backend port 8000 is listening**
|
||||
```powershell
|
||||
netstat -ano | findstr :8000
|
||||
# Should show LISTENING on 0.0.0.0:8000
|
||||
```
|
||||
|
||||
- [ ] **Backend health check responds**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
# Should return 200 OK
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot .env has correct BACKEND_URL**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
# Must be: BACKEND_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot service restarted after .env changes**
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
- [ ] **Test full linking flow**
|
||||
- Generate code in web frontend
|
||||
- Send code to @ROA2WEBBot: `/start CODE12345`
|
||||
- Should receive success message (not connection error)
|
||||
|
||||
---
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Issue 1: Port 8002 Already in Use
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot service fails to start
|
||||
- Logs show "Address already in use" or "Port 8002 is already allocated"
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Find process using port 8002
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Kill the process (replace <PID> with actual process ID)
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# Restart telegram bot service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 2: Firewall Blocking Localhost
|
||||
|
||||
**Symptoms:**
|
||||
- Backend cannot reach http://localhost:8002
|
||||
- Connection timeout errors in backend logs
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Add firewall rule for port 8002 (localhost only)
|
||||
New-NetFirewallRule -DisplayName "ROA2WEB Telegram Bot Internal API" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow -LocalAddress 127.0.0.1
|
||||
```
|
||||
|
||||
#### Issue 3: Wrong Bot Token
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot service runs but doesn't respond to commands
|
||||
- Logs show "Unauthorized" or "Invalid bot token"
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Update .env with correct token from @BotFather
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Change TELEGRAM_BOT_TOKEN to production bot token:
|
||||
# TELEGRAM_BOT_TOKEN=<production_bot_token>
|
||||
|
||||
# Restart service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 4: SQLite Database Locked
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot logs show "database is locked" errors
|
||||
- Commands fail intermittently
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Stop service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Wait 10 seconds for locks to release
|
||||
Start-Sleep -Seconds 10
|
||||
|
||||
# Start service
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 5: Backend Service Not Running
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot logs show "Cannot connect to backend" errors
|
||||
- `httpcore.ConnectError: All connection attempts failed`
|
||||
- Linking codes are found but linking fails
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Check backend service status
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# If stopped, start it
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
.\Start-ROA2WEB.ps1
|
||||
|
||||
# Verify backend is listening on port 8000
|
||||
netstat -ano | findstr :8000
|
||||
|
||||
# Test backend health
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
**Check backend logs for startup errors:**
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
|
||||
```
|
||||
|
||||
**Common backend startup issues:**
|
||||
- Oracle database not accessible
|
||||
- Missing environment variables in backend `.env`
|
||||
- Port 8000 already in use by another process
|
||||
- Python dependencies not installed
|
||||
|
||||
#### Issue 6: Wrong Backend URL in Telegram Bot
|
||||
|
||||
**Symptoms:**
|
||||
- Connection errors to backend
|
||||
- Logs show wrong URL (e.g., `http://localhost:8001` instead of `http://localhost:8000`)
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Edit telegram bot .env
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Ensure this line is correct:
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
# (Production uses port 8000, not 8001 which is dev port)
|
||||
|
||||
# Restart telegram bot service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Verification Steps
|
||||
|
||||
After fixing, verify the complete flow works:
|
||||
|
||||
1. **Backend can save codes to telegram bot:**
|
||||
```powershell
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
|
||||
```
|
||||
Expected: `201 Created` with success message
|
||||
|
||||
2. **Telegram bot can verify codes:**
|
||||
```powershell
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01"}'
|
||||
```
|
||||
Expected: `200 OK` with `"valid":true`
|
||||
|
||||
3. **End-to-end test from web frontend:**
|
||||
- Open web app: http://10.0.20.36
|
||||
- Login with Oracle credentials
|
||||
- Click "Link Telegram Account"
|
||||
- Copy the 8-character code
|
||||
- Send to @ROA2WEBBot: `/start CODE12345`
|
||||
- Should receive: "Contul tău Telegram a fost asociat cu succes!"
|
||||
|
||||
### Getting Help
|
||||
|
||||
If issues persist after following this guide:
|
||||
|
||||
1. **Collect diagnostic information:**
|
||||
```powershell
|
||||
# Service status
|
||||
Get-Service ROA2WEB-TelegramBot | Format-List *
|
||||
|
||||
# Port listening
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Recent logs (last 100 lines)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 100
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
|
||||
# Backend logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 100
|
||||
```
|
||||
|
||||
2. **Check configuration files:**
|
||||
```powershell
|
||||
# Backend .env (sanitize sensitive data before sharing!)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Telegram bot .env (sanitize bot token before sharing!)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
```
|
||||
|
||||
3. **Contact support** with the collected diagnostic information.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
### Service Management
|
||||
```powershell
|
||||
# Check status
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Start
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
|
||||
# Stop
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Restart
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```powershell
|
||||
# Watch logs in real-time
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Wait -Tail 50
|
||||
|
||||
# Check health
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Check database stats
|
||||
Invoke-WebRequest http://localhost:8002/internal/stats
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```powershell
|
||||
# Edit backend config
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Edit telegram bot config
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Restart after changes
|
||||
Restart-Service ROA2WEB-Backend
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
Reference in New Issue
Block a user