littleshop/TeleBot/DEPLOYMENT.md

TeleBot Docker Deployment on Portainer

Prerequisites

1. Portainer-01 instance running
2. LittleShop API deployed and accessible
3. Telegram Bot Token from @BotFather
4. Admin Chat ID for notifications

Quick Deployment Steps

1. Prepare Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env with your values:

• TELEGRAM_BOT_TOKEN - Your bot token from @BotFather
• TELEGRAM_ADMIN_CHAT_ID - Your Telegram chat ID for admin notifications
• LITTLESHOP_API_URL - URL to your LittleShop API instance
• DATABASE_ENCRYPTION_KEY - 32-character secure key for database encryption

2. Deploy via Portainer UI

1. Access Portainer at your portainer-01 URL
2. Navigate to Stacks → Add Stack
3. Stack Name: littleshop-telebot
4. Build Method: Repository
5. Repository URL: Your git repository URL
6. Repository Reference: main/master
7. Compose Path: TeleBot/docker-compose.yml
8. Environment Variables: Upload your .env file or add manually

3. Deploy via Portainer API (Alternative)

# Upload stack via Portainer API
curl -X POST \
  http://portainer-01:9000/api/stacks \
  -H "X-API-Key: YOUR_PORTAINER_API_KEY" \
  -F "Name=littleshop-telebot" \
  -F "StackFileContent=@docker-compose.yml" \
  -F "Env=@.env"

4. Manual Docker Deploy (If not using Portainer)

# Build and start services
docker-compose up -d

# View logs
docker-compose logs -f telebot

# Stop services
docker-compose down

Configuration Details

Required Environment Variables

Variable	Description	Example
TELEGRAM_BOT_TOKEN	Bot token from @BotFather	7880403661:AAGma1wAyoHsmG45iO6VvHCqzimhJX1pp14
TELEGRAM_ADMIN_CHAT_ID	Admin chat ID for notifications	123456789
LITTLESHOP_API_URL	LittleShop API endpoint	https://api.yourshop.com
DATABASE_ENCRYPTION_KEY	32-char encryption key	your_secure_32_character_key_here

Optional Variables

Variable	Default	Description
REDIS_ENABLED	false	Enable Redis caching
HANGFIRE_ENABLED	false	Enable background job processing
LITTLESHOP_USERNAME	admin	API admin username
LITTLESHOP_PASSWORD	admin	API admin password

Networking

The stack creates a littleshop-network bridge network for service communication.

Connecting to External LittleShop API

If your LittleShop API runs on the host or different container:

• Use host.docker.internal:5001 for same-host deployment
• Use https://your-api-domain.com for external API

Persistent Storage

Volumes Created

• littleshop-telebot-data - Bot database and application data
• littleshop-telebot-logs - Application logs
• littleshop-redis-data - Redis data (if enabled)

Data Backup

# Backup bot data
docker run --rm -v littleshop-telebot-data:/data -v $(pwd):/backup alpine tar czf /backup/telebot-backup.tar.gz /data

# Restore bot data
docker run --rm -v littleshop-telebot-data:/data -v $(pwd):/backup alpine tar xzf /backup/telebot-backup.tar.gz -C /

Health Monitoring

The bot includes health checks:

• Endpoint: Container process check
• Interval: 30 seconds
• Timeout: 10 seconds
• Retries: 3

Security Considerations

1. Database Encryption: Use a strong 32-character encryption key
2. Redis Password: Set secure Redis password if enabled
3. Network Isolation: Bot runs in isolated Docker network
4. Non-Root User: Container runs as non-root telebot user
5. Secret Management: Use Docker secrets or external secret management

Troubleshooting

Check Container Status

docker-compose ps

View Logs

# All services
docker-compose logs

# Bot only
docker-compose logs telebot

# Follow logs
docker-compose logs -f telebot

Access Container Shell

docker-compose exec telebot /bin/bash

Common Issues

1. Bot Token Invalid: Verify token with @BotFather
2. API Connection Failed: Check LITTLESHOP_API_URL and network connectivity
3. Permission Denied: Ensure proper file permissions on volumes
4. Build Failed: Check Docker build context includes LittleShop.Client project

Monitoring & Maintenance

Log Rotation

Logs are automatically rotated:

• Max size: 10MB per file
• Max files: 3 files retained

Resource Usage

Typical resource requirements:

• CPU: 0.5 cores
• Memory: 512MB
• Storage: 1GB for data + logs

Updates

To update the bot:

# Pull latest changes
git pull

# Rebuild and restart
docker-compose up -d --build

Integration with Portainer

Stack Templates

Create a custom template in Portainer for easy redeployment:

1. Portainer → App Templates → Custom Templates
2. Add Template with docker-compose.yml content
3. Variables section with environment variable definitions

Webhooks

Enable webhooks for automated deployments:

1. Stack → Webhooks → Create Webhook
2. Use webhook URL in CI/CD pipeline for automated updates

Support

For deployment issues:

1. Check container logs: docker-compose logs telebot
2. Verify environment variables in Portainer stack
3. Test API connectivity from container
4. Review bot registration in LittleShop admin panel