From 7dd48ea5a5e40cbb3a03852410c40e5a316b034d Mon Sep 17 00:00:00 2001 From: SysAdmin Date: Fri, 10 Oct 2025 13:12:34 +0100 Subject: [PATCH] docs: Add development branch deployment guide --- DEVELOPMENT_BRANCH_DEPLOYMENT.md | 360 +++++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 DEVELOPMENT_BRANCH_DEPLOYMENT.md diff --git a/DEVELOPMENT_BRANCH_DEPLOYMENT.md b/DEVELOPMENT_BRANCH_DEPLOYMENT.md new file mode 100644 index 0000000..9883156 --- /dev/null +++ b/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