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:

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

```bash
ssh sysadmin@10.0.0.51
cd ~/littleshop
```

### 2. Pull Latest Code

```bash
git pull origin main
```

### 3. Build Docker Images

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

### 4. Stop Existing Containers

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

### 5. Reset Database (Fresh Start)

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

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

### 7. Start LittleShop

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

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

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

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

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

```bash
# 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](./SILVERPAY_SETUP.md) for configuration guide.

### Bot Registration

See [BOT_REGISTRATION.md](./BOT_REGISTRATION.md) for first-time bot setup.

## 🔍 Monitoring & Troubleshooting

### View Logs

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

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

### Health Checks

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

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

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

```bash
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](./CI_CD_CT109_PREPRODUCTION.md)
- **E2E Test Results:** [CT109_E2E_TEST_RESULTS.md](./CT109_E2E_TEST_RESULTS.md)
- **SilverPay Setup:** [SILVERPAY_SETUP.md](./SILVERPAY_SETUP.md)
- **Bot Registration:** [BOT_REGISTRATION.md](./BOT_REGISTRATION.md)
- **Deployment Checklist:** [DEPLOYMENT-CHECKLIST.md](./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