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

```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