docs: Add development branch deployment guide
This commit is contained in:
parent
7008a95df3
commit
7dd48ea5a5
360
DEVELOPMENT_BRANCH_DEPLOYMENT.md
Normal file
360
DEVELOPMENT_BRANCH_DEPLOYMENT.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user