roa2web-service-auto/deployment/windows/docs/TELEGRAM_BOT_DEPLOYMENT.md

ROA2WEB Telegram Bot - Windows Server Deployment Guide

Target Server: Windows Server (10.0.20.36) Deployment Method: Windows Service (NSSM) - No Docker Service Name: ROA2WEB-TelegramBot Internal API Port: 8002 Created: 2025-10-22 Last Updated: 2025-10-22

---

Table of Contents

1. Overview
2. Prerequisites
3. Deployment Architecture
4. Installation Steps
5. Configuration
6. Service Management
7. Database Backup
8. Monitoring & Troubleshooting
9. Security Considerations
10. 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 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:

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)

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

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:

notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

Required Configuration:

# 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!):

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:

# 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

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:

Get-Service ROA2WEB-TelegramBot

Expected: Status = Running

Check Health Endpoint:

Invoke-WebRequest http://localhost:8002/internal/health | ConvertFrom-Json

Expected Output:

{
  "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:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

---

Service Management

Start Service

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Start-TelegramBot.ps1

Stop Service

.\Stop-TelegramBot.ps1

Restart Service

.\Restart-TelegramBot.ps1

Check Service Status

Get-Service ROA2WEB-TelegramBot

# Detailed info
Get-Service ROA2WEB-TelegramBot | Select-Object *

View Logs

Real-time Logs (tail -f equivalent):

Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50 -Wait

Error Logs:

Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100

Backup Logs:

Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\backup.log -Tail 50

---

Database Backup

Manual Backup

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

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:

Get-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"

Run Backup Manually (via Task Scheduler):

Start-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"

Restore from Backup

1. Stop service:

   .\Stop-TelegramBot.ps1
   

2. Find backup file:

   Get-ChildItem C:\inetpub\wwwroot\roa2web\telegram-bot\backups | Sort-Object LastWriteTime -Descending
   

3. Extract backup (if compressed):

   Expand-Archive -Path "backups\telegram_bot_backup_YYYYMMDD-HHMMSS.db.zip" -DestinationPath "temp\"
   

4. Replace database:

   Copy-Item -Path "temp\telegram_bot_backup_YYYYMMDD-HHMMSS.db" -Destination "data\telegram_bot.db" -Force
   

5. Start service:

   .\Start-TelegramBot.ps1
   

---

Monitoring & Troubleshooting

Health Checks

Service Health:

Get-Service ROA2WEB-TelegramBot | Select-Object Name, Status, StartType

API Health:

Invoke-WebRequest http://localhost:8002/internal/health

Database Stats:

(Invoke-WebRequest http://localhost:8002/internal/stats).Content | ConvertFrom-Json

Common Issues

Service Won't Start

Symptoms: Service shows "Stopped" or "Starting" forever

Diagnosis:

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:

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

   Get-Service ROA2WEB-TelegramBot
   

2. Check health endpoint:

   Invoke-WebRequest http://localhost:8002/internal/health
   

3. Check logs for errors:

   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:

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

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

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

# 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):

   ./Build-TelegramBot.ps1
   

2. Transfer to server:

   Copy-Item -Path ./deploy-package/telegram-bot -Destination \\10.0.20.36\C$\Temp\telegram-bot-update -Recurse
   

3. Deploy update (server):

   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:

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

-- 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):

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

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:

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:

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