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,502 +0,0 @@
|
||||
# 🐳 Docker Testing Guide - ROA2WEB Telegram Bot
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This guide references the OLD microservices architecture (separate Telegram container on port 8002).
|
||||
> The current architecture is an **ultrathin monolith** where the Telegram bot runs as a background
|
||||
> task within the main backend (port 8000/8001). No separate Docker container needed for Telegram.
|
||||
|
||||
This guide provides instructions for testing the Telegram bot Docker deployment.
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before testing Docker deployment:
|
||||
|
||||
- [ ] Docker Engine installed (version 20.10+)
|
||||
- [ ] Docker Compose installed (version 2.0+)
|
||||
- [ ] At least 2GB RAM available for containers
|
||||
- [ ] At least 10GB disk space available
|
||||
|
||||
## 🔍 Pre-Build Verification
|
||||
|
||||
### 1. Check Dockerfile Syntax
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/backend/modules/telegram
|
||||
|
||||
# Verify Dockerfile exists and is valid
|
||||
cat Dockerfile
|
||||
|
||||
# Check for common issues
|
||||
grep -n "COPY\|RUN\|ENV" Dockerfile
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Multi-stage build with `builder` and `production` stages
|
||||
- Non-root user `telegrambot` created
|
||||
- All required dependencies installed
|
||||
- Tini init system configured
|
||||
- Health check defined
|
||||
|
||||
### 2. Verify Required Files
|
||||
|
||||
```bash
|
||||
# Check all required files exist
|
||||
ls -la app/
|
||||
ls -la requirements.txt
|
||||
ls -la .env.example
|
||||
ls -la Dockerfile
|
||||
```
|
||||
|
||||
**Required files**:
|
||||
- ✅ `Dockerfile`
|
||||
- ✅ `requirements.txt`
|
||||
- ✅ `.env.example`
|
||||
- ✅ `app/` directory with all modules
|
||||
- ✅ `.dockerignore` (optional but recommended)
|
||||
|
||||
### 3. Check .dockerignore
|
||||
|
||||
```bash
|
||||
cat .dockerignore
|
||||
```
|
||||
|
||||
**Should exclude**:
|
||||
- `venv/`
|
||||
- `__pycache__/`
|
||||
- `*.pyc`
|
||||
- `.env`
|
||||
- `data/*.db`
|
||||
- `.git/`
|
||||
- `tests/`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Build Tests
|
||||
|
||||
### Test 1: Build Telegram Bot Image
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/backend/modules/telegram
|
||||
|
||||
# Build the image
|
||||
docker build -t roa2web/telegram-bot:test --target production .
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Build completes without errors
|
||||
- ✅ Both stages (builder + production) execute
|
||||
- ✅ Final image size < 500MB (typically ~300-400MB)
|
||||
- ✅ No security warnings in output
|
||||
|
||||
**Troubleshooting**:
|
||||
- If build fails at requirements install → check `requirements.txt` syntax
|
||||
- If permission errors → ensure Dockerfile uses correct user
|
||||
- If large image size → verify multi-stage build is working
|
||||
|
||||
### Test 2: Inspect Built Image
|
||||
|
||||
```bash
|
||||
# Check image size
|
||||
docker images roa2web/telegram-bot:test
|
||||
|
||||
# Inspect image details
|
||||
docker inspect roa2web/telegram-bot:test
|
||||
|
||||
# Check layers
|
||||
docker history roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Image size: 300-450 MB
|
||||
- Base: `python:3.11-slim`
|
||||
- User: `telegrambot` (not root)
|
||||
- Working dir: `/app`
|
||||
- Health check configured
|
||||
|
||||
### Test 3: Build with Docker Compose
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Build telegram-bot service
|
||||
docker-compose build roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Service builds successfully
|
||||
- ✅ Image tagged as `roa2web/telegram-bot:latest`
|
||||
- ✅ No errors or warnings
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Runtime Tests
|
||||
|
||||
### Test 4: Run Standalone Container (Without Backend)
|
||||
|
||||
```bash
|
||||
# Create test .env file
|
||||
cat > .env.test <<EOF
|
||||
TELEGRAM_BOT_TOKEN=test_token_here
|
||||
CLAUDE_API_KEY=test_api_key_here
|
||||
BACKEND_URL=http://localhost:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
LOG_LEVEL=DEBUG
|
||||
EOF
|
||||
|
||||
# Run container in test mode
|
||||
docker run --rm \
|
||||
--name telegram-bot-test \
|
||||
--env-file .env.test \
|
||||
-p 8002:8002 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Container starts without errors
|
||||
- ✅ Logs show "Telegram bot starting..."
|
||||
- ✅ Database initialized at `/app/data/telegram_bot.db`
|
||||
- ✅ Internal API listening on port 8002
|
||||
- ⚠️ May fail to connect to Telegram API (expected without valid token)
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
# In another terminal:
|
||||
# Check container is running
|
||||
docker ps | grep telegram-bot-test
|
||||
|
||||
# Check logs
|
||||
docker logs telegram-bot-test
|
||||
|
||||
# Test internal API health endpoint
|
||||
curl http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
### Test 5: Run with Docker Compose (Full Stack)
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Ensure .env file exists with all required variables
|
||||
cp .env.example .env
|
||||
# Edit .env and add:
|
||||
# - TELEGRAM_BOT_TOKEN
|
||||
# - CLAUDE_API_KEY
|
||||
# - ORACLE credentials
|
||||
# - JWT secret
|
||||
|
||||
# Start just the telegram-bot service (depends on backend)
|
||||
docker-compose up roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Dependencies start first: `roa-redis`, `roa-ssh-tunnel`, `roa-backend`
|
||||
- ✅ Backend health check passes
|
||||
- ✅ Telegram bot starts and connects to backend
|
||||
- ✅ SQLite database persists in `telegram-bot-data` volume
|
||||
|
||||
**Troubleshooting**:
|
||||
```bash
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# View logs
|
||||
docker-compose logs roa-telegram-bot
|
||||
docker-compose logs roa-backend
|
||||
|
||||
# Check networks
|
||||
docker network ls | grep roa-network
|
||||
docker network inspect roa-network
|
||||
```
|
||||
|
||||
### Test 6: Health Check
|
||||
|
||||
```bash
|
||||
# Wait for service to be healthy
|
||||
docker-compose ps roa-telegram-bot
|
||||
|
||||
# Should show: (healthy)
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Health check passes after ~40 seconds (start_period)
|
||||
- ✅ Health check endpoint returns 200 OK
|
||||
- ✅ Service status shows `(healthy)`
|
||||
|
||||
**Manual health check**:
|
||||
```bash
|
||||
# Access container
|
||||
docker exec -it roa-telegram-bot /bin/bash
|
||||
|
||||
# Inside container:
|
||||
python -c "import httpx; import asyncio; asyncio.run(httpx.AsyncClient().get('http://localhost:8002/internal/health'))"
|
||||
|
||||
# Should output: 200 OK
|
||||
```
|
||||
|
||||
### Test 7: Database Persistence
|
||||
|
||||
```bash
|
||||
# Start service
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Check database file exists
|
||||
docker exec roa-telegram-bot ls -la /app/data/
|
||||
|
||||
# Expected: telegram_bot.db file
|
||||
|
||||
# Stop and remove container
|
||||
docker-compose down
|
||||
|
||||
# Start again
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Verify data persisted
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db "SELECT COUNT(*) FROM telegram_users;"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Database file persists across container restarts
|
||||
- ✅ Data remains intact in `telegram-bot-data` volume
|
||||
- ✅ No data loss
|
||||
|
||||
### Test 8: Environment Variables
|
||||
|
||||
```bash
|
||||
# Check environment variables are set
|
||||
docker exec roa-telegram-bot env | grep -E "TELEGRAM|CLAUDE|BACKEND|SQLITE"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```
|
||||
TELEGRAM_BOT_TOKEN=<your_token>
|
||||
CLAUDE_API_KEY=<your_key>
|
||||
BACKEND_URL=http://roa-backend:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
```
|
||||
|
||||
### Test 9: Network Connectivity
|
||||
|
||||
```bash
|
||||
# Test bot can reach backend
|
||||
docker exec roa-telegram-bot curl -v http://roa-backend:8000/health
|
||||
|
||||
# Test backend can reach bot internal API
|
||||
docker exec roa-backend curl -v http://roa-telegram-bot:8002/internal/health
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Both services can communicate via `roa-network`
|
||||
- ✅ DNS resolution works (service names resolve)
|
||||
- ✅ Health endpoints return 200 OK
|
||||
|
||||
### Test 10: Logs and Monitoring
|
||||
|
||||
```bash
|
||||
# View real-time logs
|
||||
docker-compose logs -f roa-telegram-bot
|
||||
|
||||
# View last 100 lines
|
||||
docker-compose logs --tail=100 roa-telegram-bot
|
||||
|
||||
# Search for errors
|
||||
docker-compose logs roa-telegram-bot | grep -i error
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Logs are readable and structured
|
||||
- ✅ No critical errors
|
||||
- ✅ Log level respects `LOG_LEVEL` env var
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Tests
|
||||
|
||||
### Test 11: User Permissions
|
||||
|
||||
```bash
|
||||
# Check container is not running as root
|
||||
docker exec roa-telegram-bot whoami
|
||||
# Expected: telegrambot
|
||||
|
||||
# Check file permissions
|
||||
docker exec roa-telegram-bot ls -la /app/
|
||||
# Expected: All files owned by telegrambot:telegrambot
|
||||
```
|
||||
|
||||
### Test 12: Port Exposure
|
||||
|
||||
```bash
|
||||
# Check exposed ports
|
||||
docker port roa-telegram-bot
|
||||
|
||||
# Should only show:
|
||||
# 8002/tcp -> 0.0.0.0:8002
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only internal API port (8002) exposed
|
||||
- ✅ No unnecessary ports open
|
||||
|
||||
### Test 13: Volume Mounts
|
||||
|
||||
```bash
|
||||
# Check volumes
|
||||
docker volume inspect roa2web_telegram-bot-data
|
||||
|
||||
# Check mount point
|
||||
docker inspect roa-telegram-bot | grep -A 10 Mounts
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only `/app/data` is mounted
|
||||
- ✅ Volume is named `telegram-bot-data`
|
||||
- ✅ No sensitive files mounted
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Integration Tests
|
||||
|
||||
### Test 14: Full Stack Integration
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
cd /path/to/roa2web
|
||||
docker-compose up -d
|
||||
|
||||
# Wait for all services to be healthy
|
||||
docker-compose ps
|
||||
|
||||
# Test complete flow:
|
||||
# 1. Backend generates auth code
|
||||
# 2. Bot verifies code
|
||||
# 3. User links account
|
||||
# 4. Bot queries backend API
|
||||
```
|
||||
|
||||
**Test Steps**:
|
||||
|
||||
1. **Generate Auth Code via Backend**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/telegram/auth/generate-code \
|
||||
-H "Authorization: Bearer <jwt_token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"telegram_user_id": 123456}'
|
||||
```
|
||||
|
||||
2. **Verify Code in Bot Database**:
|
||||
```bash
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db \
|
||||
"SELECT * FROM telegram_auth_codes WHERE telegram_user_id = 123456;"
|
||||
```
|
||||
|
||||
3. **Link via Telegram Bot**:
|
||||
- Send code to bot via Telegram app
|
||||
- Verify linking succeeds
|
||||
|
||||
4. **Query Dashboard**:
|
||||
- Ask bot: "Show dashboard for company 1"
|
||||
- Verify data is retrieved from backend
|
||||
|
||||
---
|
||||
|
||||
## 🛑 Cleanup
|
||||
|
||||
### Remove Test Containers
|
||||
|
||||
```bash
|
||||
# Stop and remove containers
|
||||
docker-compose down
|
||||
|
||||
# Remove volumes (WARNING: deletes data)
|
||||
docker-compose down -v
|
||||
|
||||
# Remove images
|
||||
docker rmi roa2web/telegram-bot:test
|
||||
docker rmi roa2web/telegram-bot:latest
|
||||
```
|
||||
|
||||
### Clean Build Cache
|
||||
|
||||
```bash
|
||||
# Remove build cache
|
||||
docker builder prune -a
|
||||
|
||||
# Remove unused images
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Results Checklist
|
||||
|
||||
| Test ID | Description | Status | Notes |
|
||||
|---------|-------------|--------|-------|
|
||||
| 1 | Build telegram-bot image | ⬜ | |
|
||||
| 2 | Inspect image | ⬜ | |
|
||||
| 3 | Build with docker-compose | ⬜ | |
|
||||
| 4 | Run standalone container | ⬜ | |
|
||||
| 5 | Run with docker-compose | ⬜ | |
|
||||
| 6 | Health check | ⬜ | |
|
||||
| 7 | Database persistence | ⬜ | |
|
||||
| 8 | Environment variables | ⬜ | |
|
||||
| 9 | Network connectivity | ⬜ | |
|
||||
| 10 | Logs and monitoring | ⬜ | |
|
||||
| 11 | User permissions | ⬜ | |
|
||||
| 12 | Port exposure | ⬜ | |
|
||||
| 13 | Volume mounts | ⬜ | |
|
||||
| 14 | Full stack integration | ⬜ | |
|
||||
|
||||
**Overall Result**: ⬜ PASS ⬜ FAIL
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### Issue 1: Build Fails - "requirements.txt not found"
|
||||
**Solution**: Ensure you're in the correct directory (`telegram-bot/`) when building
|
||||
|
||||
### Issue 2: Permission Denied Errors
|
||||
**Solution**: Check Dockerfile uses correct user and permissions are set with `chown`
|
||||
|
||||
### Issue 3: Health Check Fails
|
||||
**Solution**:
|
||||
- Check internal API is starting on port 8002
|
||||
- Verify httpx is installed in requirements.txt
|
||||
- Check logs: `docker logs roa-telegram-bot`
|
||||
|
||||
### Issue 4: Can't Connect to Backend
|
||||
**Solution**:
|
||||
- Ensure both containers are on `roa-network`
|
||||
- Check backend is healthy before starting bot
|
||||
- Use service name `roa-backend` not `localhost`
|
||||
|
||||
### Issue 5: Database Not Persisting
|
||||
**Solution**:
|
||||
- Verify volume is mounted: `docker inspect roa-telegram-bot`
|
||||
- Check volume exists: `docker volume ls | grep telegram-bot-data`
|
||||
- Ensure `/app/data` has write permissions
|
||||
|
||||
---
|
||||
|
||||
## ✅ Success Criteria
|
||||
|
||||
For Docker deployment to be considered successful:
|
||||
|
||||
- ✅ Image builds without errors
|
||||
- ✅ Container starts and runs stably
|
||||
- ✅ Health checks pass
|
||||
- ✅ Bot connects to Telegram API
|
||||
- ✅ Bot connects to backend API
|
||||
- ✅ Database persists across restarts
|
||||
- ✅ No security warnings or vulnerabilities
|
||||
- ✅ Logs are clean (no critical errors)
|
||||
- ✅ All network connectivity works
|
||||
- ✅ Full stack integration succeeds
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-21
|
||||
@@ -6,29 +6,32 @@ This checklist guides you through manual testing of the Telegram bot functionali
|
||||
|
||||
Before starting manual tests:
|
||||
|
||||
- [ ] Backend API is running (`http://localhost:8001`)
|
||||
- [ ] SSH tunnel to Oracle DB is active
|
||||
- [ ] Telegram bot is running (`python -m app.main`)
|
||||
- [ ] TELEGRAM_BOT_TOKEN is configured in `.env`
|
||||
- [ ] CLAUDE_API_KEY is configured in `.env` (if using real Claude SDK)
|
||||
- [ ] SQLite database is initialized (`data/telegram_bot.db` exists)
|
||||
- [ ] Backend API is running (`http://localhost:8000` or `8001`)
|
||||
- [ ] SSH tunnel to Oracle DB is active (Linux dev only)
|
||||
- [ ] `MODULE_TELEGRAM_ENABLED=true` in `.env`
|
||||
- [ ] `TELEGRAM_BOT_TOKEN` is configured in `.env`
|
||||
- [ ] SQLite database is initialized (auto-created on first run)
|
||||
|
||||
> **Note:** In the **ultrathin monolith** architecture, the Telegram bot runs as a background task
|
||||
> within the unified backend. There's no separate bot process to start.
|
||||
|
||||
## 📱 Test Environment Setup
|
||||
|
||||
### Start Services
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start backend API (from roa2web/)
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
# From project root - starts everything (SSH tunnel + backend + frontend)
|
||||
./start-prod.sh
|
||||
|
||||
# Terminal 2: Start Telegram bot
|
||||
cd backend/modules/telegram
|
||||
source venv/bin/activate
|
||||
python -m app.main
|
||||
# Or for testing mode:
|
||||
./start-test.sh
|
||||
|
||||
# Check status
|
||||
./status.sh
|
||||
```
|
||||
|
||||
The bot starts automatically with the backend when `MODULE_TELEGRAM_ENABLED=true`.
|
||||
|
||||
### Test User Setup
|
||||
|
||||
- [ ] Create test Oracle user account in Oracle database (if needed)
|
||||
|
||||
Reference in New Issue
Block a user