Add GitLab CI/CD deployment pipeline

- Add .gitlab-ci.yml with build, deploy, and rollback stages
- Add docker-compose.production.yml (security-compliant, no hardcoded secrets)
- Update .env.example with SilverPay integration variables
- Add GITLAB-CI-DEPLOYMENT.md documentation

Security improvements:
- All secrets in VPS .env file (never in Git)
- Environment variables without defaults (fail-fast)
- SSH key authentication for CI/CD
- VPN-only access via hq.lan

Co-Authored-By: Claude <noreply@anthropic.com>

GITLAB-CI-DEPLOYMENT.md

@@ -0,0 +1,433 @@
+# LittleShop GitLab CI/CD Deployment Guide
+
+**Last Updated:** 2025-09-27
+**Environment:** Hostinger VPS (srv1002428.hstgr.cloud)
+**Access:** VPN-only via WireGuard (http://hq.lan)
+
+---
+
+## Overview
+
+LittleShop uses GitLab CI/CD for automated deployments to the Hostinger VPS. The deployment process is security-compliant, with all sensitive credentials stored in `.env` files on the server (never in Git).
+
+### Architecture
+
+```
+Developer → GitLab → CI/CD Pipeline → SSH → Hostinger VPS
+                                              ↓
+                                    Docker Registry (local)
+                                              ↓
+                                    docker-compose up -d
+                                              ↓
+                                    http://hq.lan (VPN access)
+```
+
+---
+
+## Prerequisites
+
+### 1. GitLab Project Setup
+
+Ensure the LittleShop project is configured in GitLab:
+- **Repository:** `https://git.silverlabs.uk/SilverLABS/LittleShop.git`
+- **Protected branches:** `main` branch protected
+- **GitLab Runner:** Docker-enabled runner with `docker` tag
+
+### 2. VPS Requirements
+
+- SSH access to Hostinger VPS (port 2255)
+- Docker and docker-compose installed
+- Local Docker registry running (`localhost:5000`)
+- `/opt/littleshop` deployment directory
+- `.env` file with production secrets
+
+### 3. Network Access
+
+- WireGuard VPN connection for `hq.lan` hostname resolution
+- NPM (Nginx Proxy Manager) configured for internal routing
+
+---
+
+## GitLab CI/CD Configuration
+
+### Required CI/CD Variables
+
+Navigate to **Project → Settings → CI/CD → Variables** and add the following variables:
+
+| Variable | Type | Protected | Masked | Value |
+|----------|------|-----------|--------|-------|
+| `VPS_HOST` | Variable | ✅ Yes | ❌ No | `srv1002428.hstgr.cloud` |
+| `VPS_PORT` | Variable | ✅ Yes | ❌ No | `2255` |
+| `VPS_USER` | Variable | ✅ Yes | ❌ No | `sysadmin` |
+| `VPS_SSH_KEY_B64` | File | ✅ Yes | ✅ Yes | (see below) |
+
+#### Generating VPS_SSH_KEY_B64
+
+1. **On your local machine**, create a deployment SSH key:
+   ```bash
+   ssh-keygen -t ed25519 -f ~/.ssh/littleshop_deploy_key -C "gitlab-ci-littleshop"
+   # Press Enter for no passphrase (required for CI automation)
+   ```
+
+2. **Copy the public key to VPS**:
+   ```bash
+   ssh-copy-id -i ~/.ssh/littleshop_deploy_key.pub -p 2255 sysadmin@srv1002428.hstgr.cloud
+   ```
+
+3. **Test SSH access**:
+   ```bash
+   ssh -i ~/.ssh/littleshop_deploy_key -p 2255 sysadmin@srv1002428.hstgr.cloud "echo 'SSH key works!'"
+   ```
+
+4. **Base64 encode the private key**:
+   ```bash
+   cat ~/.ssh/littleshop_deploy_key | base64 -w 0
+   ```
+
+5. **Copy the output** and paste into GitLab as `VPS_SSH_KEY_B64` variable
+
+---
+
+## Deployment Workflow
+
+### Automated Deployment (via Git Tag)
+
+1. **Commit your changes** to the `main` branch:
+   ```bash
+   git add .
+   git commit -m "Add new feature"
+   git push origin main
+   ```
+
+2. **Create a version tag**:
+   ```bash
+   git tag v1.0.1
+   git push origin v1.0.1
+   ```
+
+3. **GitLab Pipeline**:
+   - **Build stage**: Builds Docker image with tag `v1.0.1`
+   - **Deploy stage**: Manual trigger - click "Play" button in GitLab UI
+   - Pipeline transfers image to VPS via SSH
+   - VPS pushes to local registry (`localhost:5000/littleshop:latest`)
+   - `docker-compose` restarts services
+   - Health check verifies deployment
+
+4. **Access the application**:
+   ```bash
+   # Via VPN
+   curl http://hq.lan/api/catalog/products
+
+   # Direct access (localhost on VPS)
+   ssh hostinger "curl http://localhost:5100/api/catalog/products"
+   ```
+
+### Manual Deployment
+
+If you need to deploy without GitLab CI/CD:
+
+```bash
+# SSH to VPS
+ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
+
+# Pull latest code (if using Git on VPS)
+cd /opt/littleshop
+git pull origin main
+
+# Build and deploy
+docker-compose build
+docker-compose down
+docker-compose up -d
+
+# Check status
+docker ps | grep littleshop
+docker logs littleshop-admin --tail 50
+```
+
+---
+
+## Rollback Procedure
+
+### Automated Rollback (via GitLab)
+
+If a deployment fails or introduces bugs:
+
+1. **Navigate to GitLab Pipeline** for the failed deployment
+2. **Find the "rollback:vps" job** in the deploy stage
+3. **Click "Play"** to trigger rollback
+4. Pipeline restores previous image from `localhost:5000/littleshop:previous`
+5. Services restart with previous version
+6. Health check verifies rollback
+
+### Manual Rollback
+
+```bash
+# SSH to VPS
+ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
+
+# List available image tags
+docker images localhost:5000/littleshop
+
+# Tag previous version as latest
+docker tag localhost:5000/littleshop:v1.0.0 localhost:5000/littleshop:latest
+
+# Restart services
+cd /opt/littleshop
+docker-compose down
+docker-compose up -d
+
+# Verify
+curl http://localhost:5100/api/catalog/products
+```
+
+---
+
+## Security Best Practices
+
+### ✅ Implemented Security Measures
+
+- **No secrets in Git** - All credentials in VPS `.env` file only
+- **SSH key authentication** - No passwords in CI/CD
+- **Protected variables** - GitLab CI/CD variables protected and masked
+- **Localhost binding** - Port 5100 bound to `127.0.0.1` (not public)
+- **VPN-only access** - Service accessible via `hq.lan` (WireGuard VPN)
+- **Container isolation** - Dedicated Docker network
+- **Health checks** - Automated verification after deployment
+- **Immutable infrastructure** - Docker images versioned and tagged
+- **Audit trail** - GitLab tracks all deployments
+
+### 🔐 Secrets Management
+
+#### VPS `.env` File Location
+```
+/opt/littleshop/.env
+```
+
+**Permissions:** `600` (owner read/write only)
+
+#### Required Environment Variables
+
+See `.env.example` in the repository for the full list. Key variables:
+
+- `JWT_SECRET_KEY` - 64-character secure random string
+- `SILVERPAY_URL` - SilverPay API endpoint (e.g., `http://silverpay-api:8000`)
+- `SILVERPAY_API_KEY` - API authentication key
+- `SILVERPAY_WEBHOOK_SECRET` - Webhook signature verification secret
+- `SILVERPAY_WEBHOOK_URL` - Callback URL for payment notifications
+
+#### Updating Secrets
+
+1. **Connect to VPS via SSH**:
+   ```bash
+   ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
+   ```
+
+2. **Edit .env file** (use a secure editor):
+   ```bash
+   nano /opt/littleshop/.env
+   ```
+
+3. **Restart services** to apply changes:
+   ```bash
+   cd /opt/littleshop
+   docker-compose restart
+   ```
+
+4. **Verify** service is healthy:
+   ```bash
+   docker logs littleshop-admin --tail 20
+   curl http://localhost:5100/api/catalog/products
+   ```
+
+---
+
+## Troubleshooting
+
+### Pipeline Fails at Build Stage
+
+**Symptom:** Docker build fails with error messages
+
+**Solutions:**
+- Check Dockerfile syntax and base image availability
+- Verify GitLab Runner has sufficient disk space
+- Review build logs in GitLab pipeline
+
+### Pipeline Fails at Deploy Stage
+
+**Symptom:** SSH connection or deployment fails
+
+**Solutions:**
+1. **Verify SSH key**:
+   ```bash
+   # Test SSH access manually
+   ssh -i ~/.ssh/littleshop_deploy_key -p 2255 sysadmin@srv1002428.hstgr.cloud
+   ```
+
+2. **Check VPS_SSH_KEY_B64 variable**:
+   - Ensure it's correctly base64-encoded
+   - No extra newlines or spaces
+   - Protected and masked in GitLab
+
+3. **Check VPS disk space**:
+   ```bash
+   ssh hostinger "df -h"
+   ```
+
+### Health Check Fails
+
+**Symptom:** Deployment completes but health check fails
+
+**Solutions:**
+1. **Check container logs**:
+   ```bash
+   ssh hostinger "docker logs littleshop-admin --tail 50"
+   ```
+
+2. **Verify .env file** has all required variables:
+   ```bash
+   ssh hostinger "cat /opt/littleshop/.env"
+   ```
+
+3. **Test health endpoint manually**:
+   ```bash
+   ssh hostinger "curl -v http://localhost:5100/api/catalog/products"
+   ```
+
+4. **Check database file permissions**:
+   ```bash
+   ssh hostinger "ls -la /opt/littleshop/data/"
+   ```
+
+### Container Won't Start
+
+**Symptom:** Container exits immediately or won't start
+
+**Solutions:**
+1. **Check environment variables**:
+   ```bash
+   docker exec littleshop-admin env | grep -E "(JWT|SILVERPAY)"
+   ```
+
+2. **Verify database connectivity**:
+   ```bash
+   docker exec littleshop-admin ls -la /app/data/
+   ```
+
+3. **Review startup logs**:
+   ```bash
+   docker logs littleshop-admin
+   ```
+
+---
+
+## Monitoring & Maintenance
+
+### Health Checks
+
+The application includes built-in health checks:
+
+```bash
+# HTTP health check (catalog endpoint)
+curl http://hq.lan/api/catalog/products
+
+# Docker health status
+ssh hostinger "docker ps --filter name=littleshop --format 'table {{.Names}}\t{{.Status}}'"
+```
+
+### Log Management
+
+Logs are configured with rotation (10MB max, 3 files):
+
+```bash
+# View recent logs
+ssh hostinger "docker logs littleshop-admin --tail 100"
+
+# Follow logs in real-time
+ssh hostinger "docker logs littleshop-admin --follow"
+
+# Check application logs
+ssh hostinger "ls -lh /opt/littleshop/logs/"
+```
+
+### Backup Recommendations
+
+**Critical data to backup:**
+- `/opt/littleshop/data/` - SQLite database
+- `/opt/littleshop/uploads/` - Product images
+- `/opt/littleshop/.env` - Environment secrets (encrypted backup)
+
+**Suggested backup script:**
+```bash
+#!/bin/bash
+DATE=$(date +%Y%m%d-%H%M%S)
+BACKUP_DIR="/opt/backups/littleshop"
+
+# Create backup
+mkdir -p "$BACKUP_DIR"
+tar -czf "$BACKUP_DIR/littleshop-$DATE.tar.gz" \
+  -C /opt/littleshop \
+  data/ uploads/ .env
+
+# Encrypt backup
+gpg --encrypt --recipient admin@silverlabs.uk "$BACKUP_DIR/littleshop-$DATE.tar.gz"
+
+# Clean old backups (keep 30 days)
+find "$BACKUP_DIR" -name "*.tar.gz.gpg" -mtime +30 -delete
+```
+
+---
+
+## Integration with Other Services
+
+### SilverPay Payment Gateway
+
+LittleShop integrates with SilverPay for cryptocurrency payment processing.
+
+**Network Connectivity:**
+- Both containers on same Docker bridge network
+- SilverPay accessible at `http://silverpay-api:8000` (internal)
+- External access via `http://bank.lan` (VPN)
+
+**Webhook Configuration:**
+- LittleShop webhook: `http://littleshop-admin:5000/api/orders/payments/webhook`
+- Signature verification enabled (`AllowUnsignedWebhooks=false`)
+
+### TeleBot (Telegram Bot)
+
+TeleBot may integrate with LittleShop for order management.
+
+**Configuration:**
+- TeleBot should use `http://hq.lan` or `http://littleshop-admin:5000`
+- API authentication via JWT tokens
+- Ensure TeleBot has network access to LittleShop container
+
+---
+
+## Support & Documentation
+
+### Related Documentation
+
+- **CLAUDE.md** - Project overview and development progress
+- **ROADMAP.md** - Development priorities and roadmap
+- **.env.example** - Environment variable template
+- **WORKING_BASELINE_2024-09-24.md** - Working configuration baseline
+
+### Infrastructure Documentation
+
+- **08-HOSTINGER-SECURITY-HARDENING.md** - Security policies and hardening
+- **06-CLIENT-INFRASTRUCTURE.md** - Client infrastructure overview
+
+### Getting Help
+
+If you encounter issues not covered in this guide:
+
+1. **Check GitLab pipeline logs** for detailed error messages
+2. **Review Docker logs** on the VPS
+3. **Verify network connectivity** (VPN, DNS, firewall)
+4. **Consult security documentation** for credential issues
+
+---
+
+**Last Tested:** 2025-09-27
+**Status:** ✅ Deployment pipeline operational
+**Next Review:** 2025-10-27