littleshop/DEPLOYMENT.md

LittleShop Deployment Guide

This guide covers deploying LittleShop and TeleBot using Gitea Actions CI/CD pipeline.

📋 Overview

LittleShop uses Gitea Actions for automated deployment to:

• CT109 Pre-Production (10.0.0.51) - Automated deployment on push to main or development
• Production VPS (srv1002428.hstgr.cloud) - Manual deployment only

🚀 Quick Deploy (Recommended - CI/CD)

The easiest and recommended way to deploy is via git push, which automatically triggers the Gitea Actions workflow:

# Make your changes
git add .
git commit -m "Your changes"

# Push to trigger automatic deployment to CT109
git push origin main         # or development branch

# Deployment happens automatically:
# 1. Gitea Actions workflow triggers
# 2. SSH connection to CT109
# 3. Code cloned/updated to ~/littleshop
# 4. Docker images built on CT109
# 5. Database volume deleted (fresh start)
# 6. Containers started with fresh database
# 7. Health checks verify deployment

What Happens Automatically

The CI/CD pipeline (.gitea/workflows/build-and-deploy.yml) automatically:

1. ✅ Connects to CT109 via SSH
2. ✅ Clones/updates code to ~/littleshop directory
3. ✅ Builds Docker images with --no-cache
4. ✅ Stops existing containers
5. ✅ Deletes database volume for fresh start (backup created first!)
6. ✅ Creates networks (littleshop-network, silverpay-network)
7. ✅ Starts LittleShop on port 5100:5000
8. ✅ Starts TeleBot with proper networking
9. ✅ Runs health checks to verify deployment

Fresh Database on Every Deployment

IMPORTANT: Every deployment now automatically:

• Creates timestamped backup of existing database
• Deletes the database volume completely
• Starts with 100% fresh database (only admin user, no products/orders/customers)

This ensures consistent, repeatable testing environments.

🌍 Deployment Environments

CT109 Pre-Production (10.0.0.51)

Deployment Path: ~/littleshop (home directory of deploy user)

Configuration:

• Environment: Development
• Port: 5100:5000 (host:container)
• Database: littleshop-dev.db (fresh on every deploy)
• Networks: littleshop-network + silverpay-network
• Sample Data: Disabled in Production/Development environments

Access Points:

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

Production VPS (srv1002428.hstgr.cloud)

Deployment Path: /opt/littleshop

Configuration:

• Environment: Production
• Port: 5100:5000 (host:container)
• Database: littleshop-production.db (fresh on every deploy)
• Networks: littleshop_littleshop-network + silverpay_silverpay-network
• Deployment: Manual only via workflow_dispatch

Access Points:

• API: https://admin.dark.side/api
• Admin Panel: https://admin.dark.side/Admin

🔐 Required Gitea Secrets

Configure these secrets in Gitea repository settings under Settings → Secrets:

CT109 Pre-Production Secrets

CT109_HOST                   = 10.0.0.51
CT109_SSH_PORT              = 22
CT109_USER                  = sysadmin
CT109_SSH_KEY               = <SSH private key>
CT109_TELEGRAM_BOT_TOKEN    = <Telegram bot token for CT109>

Production VPS Secrets

VPS_HOST                    = srv1002428.hstgr.cloud
VPS_PORT                    = 2255
VPS_USER                    = sysadmin
VPS_SSH_KEY                = <SSH private key>
TELEGRAM_BOT_TOKEN          = <Telegram bot token for production>

📦 Manual Deployment (Not Recommended)

If you need to deploy manually without CI/CD (for troubleshooting):

1. SSH to CT109

ssh sysadmin@10.0.0.51
cd ~/littleshop

2. Pull Latest Code

git pull origin main

3. Build Docker Images

docker build --no-cache -t littleshop:latest .
docker build --no-cache -t telebot:latest -f Dockerfile.telebot .

4. Stop Existing Containers

docker stop littleshop telebot-service 2>/dev/null || true
docker rm littleshop telebot-service 2>/dev/null || true

5. Reset Database (Fresh Start)

# Backup existing database
docker run --rm -v littleshop-data:/data -v $(pwd):/backup alpine sh -c \
  "if [ -f /data/littleshop-dev.db ]; then cp /data/littleshop-dev.db /backup/littleshop-dev.db.backup-$(date +%Y%m%d-%H%M%S); fi"

# Delete database volume
docker volume rm littleshop-data

6. Create Networks

docker network create littleshop-network 2>/dev/null || true
docker network create silverpay-network 2>/dev/null || true

7. Start LittleShop

docker run -d \
  --name littleshop \
  --restart unless-stopped \
  --network littleshop-network \
  -p 5100:5000 \
  -v littleshop-data:/app/data \
  -e ASPNETCORE_URLS=http://+:5000 \
  -e ASPNETCORE_ENVIRONMENT=Development \
  littleshop:latest

8. Start TeleBot

docker run -d \
  --name telebot-service \
  --restart unless-stopped \
  --network silverpay-network \
  -e ASPNETCORE_URLS=http://+:5010 \
  -e LittleShop__ApiUrl=http://littleshop:5000 \
  -e LittleShop__UseTor=false \
  -e Telegram__BotToken=YOUR_BOT_TOKEN_HERE \
  telebot:latest

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

9. Verify Deployment

# Wait for startup
sleep 15

# Check containers
docker ps --filter "name=littleshop" --filter "name=telebot"

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

# Check logs
docker logs littleshop --tail 50
docker logs telebot-service --tail 30

🏗️ Network Architecture

┌─────────────────────────────────────────────┐
│ CT109 Docker Host (10.0.0.51)              │
│                                             │
│  ┌──────────────┐      ┌─────────────────┐ │
│  │  littleshop  │◄─────┤ telebot-service │ │
│  │  :5000       │      │                 │ │
│  └──────────────┘      └─────────────────┘ │
│        ▲                        │           │
│        │                        │           │
│    Port 5100               littleshop-     │
│   (Host Access)            network         │
│                                │            │
│                          silverpay-        │
│                          network           │
│                                │            │
│                      ┌─────────▼─────────┐ │
│                      │ SilverPay         │ │
│                      │ (10.0.0.51:5500)  │ │
│                      │ (NOT RUNNING)     │ │
│                      └───────────────────┘ │
└─────────────────────────────────────────────┘

🗄️ Database Management

Backup Database

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

Restore Database

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

# Restart container
docker restart littleshop

Manual Database Reset

If you need to manually reset the database without redeploying:

# Stop containers
docker stop littleshop telebot-service

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

# Restart containers (fresh database will be created)
docker start littleshop
docker start telebot-service

⚙️ Configuration

Environment Variables

LittleShop:

• ASPNETCORE_ENVIRONMENT - Development | Production
• ASPNETCORE_URLS - http://+:5000
• ConnectionStrings__DefaultConnection - Database path
• Jwt__Key - JWT signing key (32+ characters)

TeleBot:

• LittleShop__ApiUrl - http://littleshop:5000
• LittleShop__UseTor - false
• Telegram__BotToken - From Gitea secrets

SilverPay Integration

See SILVERPAY_SETUP.md for configuration guide.

Bot Registration

See BOT_REGISTRATION.md for first-time bot setup.

🔍 Monitoring & Troubleshooting

View Logs

# Real-time logs
docker logs -f littleshop
docker logs -f telebot-service

# Last 100 lines
docker logs --tail=100 littleshop

Health Checks

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

# Expected output:
# {"version":"1.0.0","environment":"Development"}

# Product catalog (should be empty on fresh deploy)
curl http://localhost:5100/api/catalog/products

# Expected output:
# {"items":[],"totalCount":0}

Common Issues

"Name or service not known"

Symptom: TeleBot can't connect to LittleShop

Solution: Verify both containers are on littleshop-network:

docker inspect littleshop | grep NetworkMode
docker inspect telebot-service | grep NetworkMode

# Should both show: littleshop-network

"Connection refused on port 5000"

Symptom: TeleBot gets connection refused

Solution: Verify LittleShop is listening on port 5000:

docker exec littleshop netstat -tlnp | grep 5000

# Or check environment
docker exec littleshop env | grep ASPNETCORE_URLS
# Should output: ASPNETCORE_URLS=http://+:5000

Sample Data Appears

Symptom: Products/categories pre-populated

Solution: Verify environment is set to Production or Development:

docker exec littleshop env | grep ASPNETCORE_ENVIRONMENT

# Should output: ASPNETCORE_ENVIRONMENT=Development
# (Sample data is disabled in both Development and Production since commit c4caee9)

🎯 Deployment Checklist

Before deploying:

• All code changes committed and pushed to git
• Gitea secrets configured (bot token, SSH key, etc.)
• SilverPay integration configured (if needed)
• Bot token valid for environment (CT109 vs Production)
• Network names correct (no docker-compose prefix confusion)
• Confirm fresh database is acceptable (data will be lost)

After deployment:

• Health check passes (/api/version returns 200)
• Product catalog is empty (0 products)
• Admin panel accessible (default: admin/admin)
• TeleBot connects successfully to LittleShop API
• Bot registration workflow tested

📚 Additional Documentation

• CI/CD Details: CI_CD_CT109_PREPRODUCTION.md
• E2E Test Results: CT109_E2E_TEST_RESULTS.md
• SilverPay Setup: SILVERPAY_SETUP.md
• Bot Registration: BOT_REGISTRATION.md
• Deployment Checklist: DEPLOYMENT-CHECKLIST.md

🆘 Getting Help

If deployment fails:

1. Check Gitea Actions logs for detailed error messages
2. SSH to CT109 and check container logs
3. Verify all Gitea secrets are correctly configured
4. Review network connectivity between containers
5. Confirm database volume was successfully deleted/recreated