littleshop/DEPLOYMENT.md

LittleShop Deployment Guide

This guide covers deploying LittleShop and TeleBot using Docker and Docker Compose.

Quick Deploy (Recommended)

The easiest way to deploy is using Docker Compose, which handles networking and configuration automatically:

# Set the Telegram bot token
export TELEGRAM_BOT_TOKEN="your-bot-token-here"

# Deploy all services
docker-compose up -d

# View logs
docker-compose logs -f

This automatically:

• Creates the littleshop-network for inter-service communication
• Configures correct ports (5100:5000)
• Sets up health checks and dependencies
• Connects to external silverpay-network

Network Architecture

┌─────────────────────────────────────────────┐
│ littleshop-network (bridge)                 │
│                                             │
│  ┌──────────────┐      ┌─────────────────┐ │
│  │  littleshop  │◄─────┤ telebot-service │ │
│  │  :5000       │      │                 │ │
│  └──────────────┘      └─────────────────┘ │
│        ▲                        │           │
└────────┼────────────────────────┼───────────┘
         │                        │
    Port 5100                     │
    (Host Access)                 │
                                  │
                    ┌─────────────▼───────────┐
                    │ silverpay-network       │
                    │ (external)              │
                    └─────────────────────────┘

Manual Deployment (Alternative)

If you need to deploy manually without Docker Compose:

1. Build Images

# Build LittleShop
cd /mnt/c/Production/Source/LittleShop
docker build -t littleshop:latest .

# Build TeleBot (if not already built)
cd /mnt/c/Production/Source/TeleBot
docker build -t telebot:latest .

2. Create Network

docker network create littleshop-network

3. Deploy LittleShop

docker run -d \
  --name littleshop \
  --network littleshop-network \
  -p 5100:5000 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e ASPNETCORE_URLS=http://+:5000 \
  -e "ConnectionStrings__DefaultConnection=Data Source=/app/data/littleshop-prod.db" \
  -e "Jwt__Key=LittleShop-Production-JWT-SecretKey-32Characters-2025" \
  -e "Jwt__Issuer=LittleShop" \
  -e "Jwt__Audience=LittleShop" \
  -v littleshop-data:/app/data \
  -v littleshop-uploads:/app/wwwroot/uploads \
  -v littleshop-logs:/app/logs \
  --restart unless-stopped \
  littleshop:latest

4. Deploy TeleBot

docker run -d \
  --name telebot-service \
  --network littleshop-network \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e LittleShop__ApiUrl=http://littleshop:5000 \
  -e LittleShop__UseTor=false \
  -e "Telegram__BotToken=YOUR_BOT_TOKEN_HERE" \
  --restart unless-stopped \
  telebot:latest

# Connect to SilverPay network
docker network connect silverpay-network telebot-service

Common Issues and Solutions

Issue: "Name or service not known"

Symptom: TeleBot logs show System.Net.Sockets.SocketException: Name or service not known

Cause: Containers are on different networks

Solution:

# Verify networks
docker inspect littleshop | grep NetworkMode
docker inspect telebot-service | grep NetworkMode

# Connect to correct network
docker network connect littleshop-network littleshop
docker network connect littleshop-network telebot-service

Issue: "Connection refused" on port 5000

Symptom: TeleBot logs show Connection refused (littleshop:5000)

Cause: LittleShop listening on wrong port (usually 8080)

Solution: Ensure ASPNETCORE_URLS=http://+:5000 is set in environment variables

Issue: Sample data appears in production

Symptom: Products/categories pre-populated when expecting empty database

Cause: ASPNETCORE_ENVIRONMENT not set to Production

Solution:

# Verify environment
docker exec littleshop env | grep ASPNETCORE_ENVIRONMENT

# Should output: ASPNETCORE_ENVIRONMENT=Production

Database Management

Fresh Database (Empty State)

To start with a completely empty database (admin user only):

# Stop containers
docker-compose down

# Remove database volume
docker volume rm littleshop_littleshop-data

# Restart
docker-compose up -d

Database Backup

# Backup database
docker run --rm -v littleshop_littleshop-data:/data -v $(pwd):/backup alpine \
  sh -c "cp /data/littleshop-prod.db /backup/littleshop-backup-$(date +%Y%m%d-%H%M%S).db"

Database Restore

# Restore database
docker run --rm -v littleshop_littleshop-data:/data -v $(pwd):/backup alpine \
  sh -c "cp /backup/littleshop-backup-YYYYMMDD-HHMMSS.db /data/littleshop-prod.db"

# Restart container
docker-compose restart littleshop

Environment Configuration

Required Environment Variables

LittleShop:

• ASPNETCORE_ENVIRONMENT=Production - Disables sample data seeding
• ASPNETCORE_URLS=http://+:5000 - Forces correct internal port
• ConnectionStrings__DefaultConnection - Database path
• Jwt__Key - JWT signing key (32+ characters)
• Jwt__Issuer - JWT issuer claim
• Jwt__Audience - JWT audience claim

TeleBot:

• ASPNETCORE_ENVIRONMENT=Production - Production settings
• LittleShop__ApiUrl=http://littleshop:5000 - LittleShop connection
• LittleShop__UseTor=false - Direct connection (no Tor)
• Telegram__BotToken - Bot authentication token

Setting Bot Token

# Option 1: Export environment variable (recommended)
export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
docker-compose up -d

# Option 2: .env file (create in project root)
echo "TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz" > .env
docker-compose up -d

Access Points

• Admin Panel: http://localhost:5100/Admin
• API: http://localhost:5100/api
• Swagger Docs: http://localhost:5100/swagger
• Health Check: http://localhost:5100/api/version

Monitoring

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f littleshop
docker-compose logs -f telebot

# Last 100 lines
docker-compose logs --tail=100 telebot

Health Status

# Check container health
docker ps

# LittleShop health endpoint
curl http://localhost:5100/api/version

# Verify TeleBot connection
docker logs telebot-service | grep "Bot started successfully"

Network Connectivity Test

# Test from TeleBot container
docker exec telebot-service curl http://littleshop:5000/api/version

# Should return: {"version":"1.0.0","environment":"Production"}

Updating Services

Update LittleShop

# Pull latest code
git pull origin main

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

Update TeleBot

# Pull latest code from TeleBot repo
cd /mnt/c/Production/Source/TeleBot
git pull origin main

# Rebuild image
docker build -t telebot:latest .

# Restart service
docker-compose restart telebot

Production Checklist

Before deploying to production:

• Set ASPNETCORE_ENVIRONMENT=Production
• Configure unique JWT secret key (32+ characters)
• Set valid Telegram bot token
• Verify silverpay-network exists (docker network ls)
• Test database backup/restore process
• Verify health checks are passing
• Test TeleBot can connect to LittleShop API
• Confirm empty database (if required)
• Document any custom configuration

Troubleshooting Commands

# List all networks
docker network ls

# Inspect network
docker network inspect littleshop_littleshop-network

# Check which networks a container is on
docker inspect littleshop --format='{{json .NetworkSettings.Networks}}'

# Test DNS resolution
docker exec telebot-service nslookup littleshop

# Check listening ports
docker exec littleshop netstat -tlnp

# View environment variables
docker exec littleshop env

# Force recreate containers
docker-compose up -d --force-recreate