docs: Add development branch deployment guide

DEVELOPMENT_BRANCH_DEPLOYMENT.md

@@ -0,0 +1,360 @@
+# Development Branch Deployment Guide
+
+**Created**: 2025-10-10
+**Branch**: `development`
+**Status**: Ready for testing
+
+## Recent Changes (Commit: 7008a95)
+
+### Bot Management Improvements
+- **Fixed duplicate bot registration issue**
+  - TeleBot now checks for existing bot by Telegram username before registering
+  - Prevents multiple database entries on container restarts
+  - Auto-populates platform info (username, display name, platform ID)
+
+- **Added wallet configuration system**
+  - UI for managing cryptocurrency wallet addresses
+  - Supports: BTC, XMR, LTC, DOGE, ETH, ZEC, DASH
+  - Stored in `Bot.Settings.wallets` JSON field
+  - Used as fallback when payment gateway unavailable
+
+- **Added duplicate detection utility**
+  - Admin Bot Index page detects duplicates by platform username
+  - Visual cleanup interface with one-click delete
+  - Highlights most recent entry to keep
+
+### Files Modified
+```
+LittleShop/
+├── Controllers/BotsController.cs (new API endpoint)
+├── Services/BotService.cs (lookup by platform)
+├── Services/IBotService.cs (interface update)
+├── DTOs/BotDto.cs (wallet DTOs)
+├── Areas/Admin/Controllers/BotsController.cs (UpdateWallets action)
+├── Areas/Admin/Views/Bots/Edit.cshtml (wallet UI)
+└── Areas/Admin/Views/Bots/Index.cshtml (duplicate detection)
+
+TeleBot/
+└── Services/BotManagerService.cs (duplicate prevention logic)
+```
+
+---
+
+## Current Deployment Infrastructure
+
+### Production Environment ✅
+- **VPS**: srv1002428.hstgr.cloud (Hostinger)
+- **SSH Port**: 2255
+- **Deployment Path**: `/opt/littleshop`
+- **GitLab CI/CD**: Auto-deploys on `main` branch push
+- **Docker Registry**: localhost:5000
+- **Networks**:
+  - `littleshop_littleshop-network` (LittleShop API)
+  - `silverpay_silverpay-network` (Payment gateway + TeleBot)
+
+### Development Environment ❌
+**Currently Not Configured**
+
+GitLab CI only triggers on `main` branch:
+```yaml
+rules:
+  - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+---
+
+## Testing Options
+
+### Option 1: Local Docker Testing ✅ (Recommended First Step)
+
+**Quick validation of bot management changes:**
+
+```bash
+# Build and start local environment
+cd /mnt/c/Production/Source/LittleShop
+docker-compose up --build -d
+
+# View logs
+docker logs littleshop -f
+
+# In another terminal, monitor TeleBot
+docker logs telebot-service -f
+
+# Test bot restart behavior (verify no duplicates created)
+docker restart telebot-service
+
+# Check Admin Panel
+# Navigate to: http://localhost:5100/Admin/Bots
+# Login: admin / admin
+```
+
+**What to Test**:
+1. ✅ Bot registration on first startup
+2. ✅ No duplicate entry on container restart
+3. ✅ Wallet configuration UI in Bot Edit page
+4. ✅ Duplicate detection banner (if existing duplicates)
+5. ✅ Duplicate cleanup functionality
+
+**Stop When Done**:
+```bash
+docker-compose down
+```
+
+---
+
+### Option 2: Manual Development Deployment on VPS 📦
+
+**Deploy alongside production for real-world testing:**
+
+#### Setup Script
+```bash
+#!/bin/bash
+# deploy-development.sh - Deploy development branch to VPS
+
+VPS_HOST="srv1002428.hstgr.cloud"
+VPS_PORT="2255"
+VPS_USER="sysadmin"
+DEV_PORT_API="5101"
+DEV_PORT_TELEBOT="5011"
+
+ssh -i ~/.ssh/littleshop_deploy_key -p $VPS_PORT $VPS_USER@$VPS_HOST << 'EOF'
+  set -e
+
+  # Create development directory
+  sudo mkdir -p /opt/littleshop-dev
+  cd /opt/littleshop-dev
+
+  # Pull latest development branch
+  git clone -b development https://gitlab.silverlabs.uk/Jamie/littleshop.git . || git pull origin development
+
+  # Create dev docker-compose
+  cat > docker-compose.dev.yml << 'COMPOSE'
+version: '3.8'
+
+services:
+  littleshop-dev:
+    build: .
+    image: localhost:5000/littleshop:dev
+    container_name: littleshop-dev
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:5101:5000"
+    environment:
+      - ASPNETCORE_ENVIRONMENT=Development
+      - ASPNETCORE_URLS=http://+:5000
+      - ConnectionStrings__DefaultConnection=Data Source=/app/data/littleshop-dev.db
+    volumes:
+      - littleshop_dev_data:/app/data
+      - littleshop_dev_uploads:/app/wwwroot/uploads
+    networks:
+      - littleshop-dev-network
+
+volumes:
+  littleshop_dev_data:
+  littleshop_dev_uploads:
+
+networks:
+  littleshop-dev-network:
+    driver: bridge
+COMPOSE
+
+  # Build and start
+  docker-compose -f docker-compose.dev.yml up --build -d
+
+  echo "✅ Development environment deployed:"
+  echo "   API: http://localhost:5101"
+  echo "   Admin: http://localhost:5101/Admin"
+EOF
+```
+
+**Deploy**:
+```bash
+chmod +x deploy-development.sh
+./deploy-development.sh
+```
+
+**Access Development Environment**:
+- SSH tunnel: `ssh -L 5101:localhost:5101 -p 2255 sysadmin@srv1002428.hstgr.cloud`
+- Then open: http://localhost:5101/Admin
+
+---
+
+### Option 3: GitLab CI Development Pipeline 🔧
+
+**For automated development deployments:**
+
+#### Modify `.gitlab-ci.yml`
+Add this job after `deploy:vps`:
+
+```yaml
+deploy:development:
+  stage: deploy
+  image: docker:24
+  before_script:
+    - apk add --no-cache openssh-client bash curl
+    - echo "$VPS_SSH_KEY_B64" | base64 -d > /tmp/deploy_key
+    - chmod 600 /tmp/deploy_key
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+    - ssh-keyscan -p "$VPS_PORT" "$VPS_HOST" >> ~/.ssh/known_hosts
+  script:
+    - export VERSION="dev-${CI_COMMIT_SHORT_SHA}"
+    - echo "Deploying development version $VERSION to VPS"
+
+    # Build development images
+    - docker build --no-cache -t littleshop:$VERSION .
+    - docker build --no-cache -t telebot:$VERSION -f Dockerfile.telebot .
+
+    # Copy to VPS
+    - docker save littleshop:$VERSION | ssh -i /tmp/deploy_key -p "$VPS_PORT" "$VPS_USER@$VPS_HOST" "docker load"
+    - docker save telebot:$VERSION | ssh -i /tmp/deploy_key -p "$VPS_PORT" "$VPS_USER@$VPS_HOST" "docker load"
+
+    # Deploy to development namespace
+    - |
+      ssh -i /tmp/deploy_key -p "$VPS_PORT" "$VPS_USER@$VPS_HOST" bash -s << EOF
+      set -e
+      export VERSION="$VERSION"
+
+      cd /opt/littleshop-dev
+
+      # Tag as dev
+      docker tag littleshop:\$VERSION localhost:5000/littleshop:dev
+      docker tag telebot:\$VERSION localhost:5000/telebot:dev
+
+      # Stop existing dev containers
+      docker stop littleshop-dev telebot-dev 2>/dev/null || true
+      docker rm littleshop-dev telebot-dev 2>/dev/null || true
+
+      # Start with dev compose file
+      docker-compose -f docker-compose.dev.yml up -d
+
+      # Health check
+      sleep 10
+      curl -f http://localhost:5101/api/catalog/products || exit 1
+      echo "✅ Development deployment successful"
+      EOF
+  environment:
+    name: development
+    url: http://dev.hq.lan:5101
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "development"'
+      when: on_success
+  tags:
+    - docker
+```
+
+---
+
+## Testing Checklist
+
+### Functional Testing
+- [ ] Bot starts without errors
+- [ ] Bot registration creates single database entry
+- [ ] Container restart does NOT create duplicate entry
+- [ ] Platform info auto-populated (username, display name, bot ID)
+- [ ] Wallet configuration UI displays correctly
+- [ ] Can add/update cryptocurrency wallet addresses
+- [ ] Wallet addresses saved to Bot.Settings.wallets
+- [ ] Duplicate detection shows warning if duplicates exist
+- [ ] Can delete duplicate bot entries
+- [ ] Most recent bot entry highlighted in green
+
+### Integration Testing
+- [ ] TeleBot connects to LittleShop API
+- [ ] Bot authentication works
+- [ ] Orders can be created through bot
+- [ ] Admin panel shows correct bot information
+
+### Performance Testing
+- [ ] Bot startup time acceptable
+- [ ] API response times normal
+- [ ] No memory leaks on container restart
+
+---
+
+## Merge Process
+
+### When Ready to Deploy to Production
+
+1. **Create Merge Request**:
+   ```bash
+   # In GitLab UI or via CLI
+   git checkout development
+   git push origin development
+   # Then create MR: development → main
+   ```
+
+2. **Review Changes**:
+   - Check code diff in GitLab
+   - Verify all tests passed
+   - Confirm no breaking changes
+
+3. **Merge**:
+   - Merge via GitLab UI
+   - GitLab CI automatically deploys to production
+
+4. **Verify Production**:
+   - Check health endpoints
+   - Monitor logs: `ssh ... "docker logs littleshop -f"`
+   - Test bot registration behavior
+   - Verify wallet configuration working
+
+5. **Cleanup Development Branch** (optional):
+   - Keep branch for future development work
+   - Or delete if no longer needed
+
+---
+
+## Rollback Procedure
+
+If issues found after merge:
+
+```bash
+# GitLab CI provides manual rollback job
+# OR manually SSH to VPS:
+
+ssh -i ~/.ssh/littleshop_deploy_key -p 2255 sysadmin@srv1002428.hstgr.cloud
+
+cd /opt/littleshop
+
+# Tag previous working image as latest
+docker tag localhost:5000/littleshop:previous localhost:5000/littleshop:latest
+docker tag localhost:5000/telebot:previous localhost:5000/telebot:latest
+
+# Restart services
+docker-compose down
+docker-compose up -d
+
+# Verify
+docker logs littleshop -f
+```
+
+---
+
+## Branch Protection Status
+
+- ✅ **Main branch**: Protected from direct pushes (requires merge request)
+- ✅ **Development branch**: Allows direct pushes for development work
+- ✅ **Local push to main**: Disabled (`no_push`)
+
+---
+
+## Next Steps
+
+1. **Immediate**: Push development branch to GitLab
+2. **Short-term**: Test locally with Docker Compose
+3. **Before merge**: Deploy to development environment (Option 2 or 3)
+4. **Production**: Create MR and merge when confident
+
+---
+
+## Contact & Support
+
+**GitLab Repository**: https://gitlab.silverlabs.uk/Jamie/littleshop
+**Production VPS**: srv1002428.hstgr.cloud:2255
+**Admin Panel**: https://admin.dark.side (Nginx Proxy Manager → littleshop:5000)
+
+**Documentation**:
+- CLAUDE.md - Project progress and working baseline
+- ROADMAP.md - Development priorities
+- DEPLOYMENT.md - Production deployment guide