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:

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

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

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

```bash
# 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
```bash
docker-compose ps
```

### View Logs
```bash
# All services
docker-compose logs

# Bot only
docker-compose logs telebot

# Follow logs
docker-compose logs -f telebot
```

### Access Container Shell
```bash
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:
```bash
# 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