roa2web-service-auto/docs/telegram/testing/DOCKER_TESTING_GUIDE.md

🐳 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

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

# 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

cat .dockerignore

Should exclude:

• venv/
• __pycache__/
• *.pyc
• .env
• data/*.db
• .git/
• tests/

---

🏗️ Build Tests

Test 1: Build Telegram Bot Image

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

# 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

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)

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

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

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:

# 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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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:

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

# 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

# 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