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>

.env.example

@@ -1,14 +1,41 @@
 # LittleShop Production Environment Variables
-# Copy this file to .env and update the values
+# Copy this file to .env and update with your actual values
+# NEVER commit the .env file to Git - it contains sensitive credentials
 
-# JWT Configuration
+# =============================================================================
-JWT_SECRET_KEY=YourSuperSecretKeyThatIsAtLeast32CharactersLong!
+# JWT Configuration (REQUIRED)
+# =============================================================================
+# Generate with: openssl rand -base64 48 | cut -c1-64
+JWT_SECRET_KEY=YourSuperSecretKeyThatIsAtLeast64CharactersLongForProductionUsage
 
-# BTCPay Server Configuration (Optional)
+# =============================================================================
+# SilverPay Integration (REQUIRED for payment processing)
+# =============================================================================
+# SilverPay Base URL
+# - For VPN/LAN access: http://bank.lan or http://10.13.13.1:8001
+# - For direct access: http://31.97.57.205:8001
+SILVERPAY_URL=http://bank.lan
+
+# SilverPay API Key (get from SilverPay admin panel)
+SILVERPAY_API_KEY=your-silverpay-api-key-here
+
+# SilverPay Webhook Secret (shared secret for webhook verification)
+SILVERPAY_WEBHOOK_SECRET=your-webhook-secret-here
+
+# LittleShop Webhook URL (where SilverPay sends payment notifications)
+# - For VPN/LAN: http://hq.lan/api/orders/payments/webhook
+# - For public: http://srv1002428.hstgr.cloud:5100/api/orders/payments/webhook
+SILVERPAY_WEBHOOK_URL=http://hq.lan/api/orders/payments/webhook
+
+# =============================================================================
+# BTCPay Server Configuration (OPTIONAL - legacy, prefer SilverPay)
+# =============================================================================
 BTCPAY_SERVER_URL=https://your-btcpay-server.com
 BTCPAY_STORE_ID=your-store-id
 BTCPAY_API_KEY=your-api-key
 BTCPAY_WEBHOOK_SECRET=your-webhook-secret
 
-# Compose Project Name (Optional)
+# =============================================================================
+# Docker Compose Configuration (OPTIONAL)
+# =============================================================================
 COMPOSE_PROJECT_NAME=littleshop

.gitlab-ci.yml

@@ -0,0 +1,144 @@
+stages:
+  - build
+  - deploy
+
+variables:
+  DOCKER_DRIVER: overlay2
+  DOCKER_TLS_CERTDIR: "/certs"
+
+build:
+  stage: build
+  image: docker:24-dind
+  services:
+    - docker:24-dind
+  script:
+    - echo "Building LittleShop Docker image"
+    - docker build -t localhost:5000/littleshop:latest .
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        echo "Tagging as version $CI_COMMIT_TAG"
+        docker tag localhost:5000/littleshop:latest localhost:5000/littleshop:$CI_COMMIT_TAG
+      fi
+    - echo "Build complete"
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_TAG'
+  tags:
+    - docker
+
+deploy:vps:
+  stage: deploy
+  image: docker:24-dind
+  services:
+    - docker:24-dind
+  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:
+    - echo "Deploying version $CI_COMMIT_TAG to VPS"
+    - echo "Building image from source..."
+    - docker build -t littleshop:$CI_COMMIT_TAG .
+
+    - echo "Copying image to VPS via SSH..."
+    - docker save littleshop:$CI_COMMIT_TAG | ssh -i /tmp/deploy_key -p $VPS_PORT $VPS_USER@$VPS_HOST "docker load"
+
+    - echo "Deploying on VPS..."
+    - |
+      ssh -i /tmp/deploy_key -p $VPS_PORT $VPS_USER@$VPS_HOST bash -s << EOF
+      set -e
+
+      # Tag the image
+      docker tag littleshop:$CI_COMMIT_TAG localhost:5000/littleshop:$CI_COMMIT_TAG
+      docker tag littleshop:$CI_COMMIT_TAG localhost:5000/littleshop:latest
+
+      # Push to local registry
+      echo "Pushing to local Docker registry..."
+      docker push localhost:5000/littleshop:$CI_COMMIT_TAG
+      docker push localhost:5000/littleshop:latest
+
+      # Navigate to deployment directory
+      cd /opt/littleshop
+
+      # Stop services
+      echo "Stopping services..."
+      docker-compose down
+
+      # Start services with new image
+      echo "Starting services with new image..."
+      docker-compose up -d
+
+      # Wait for startup
+      echo "Waiting for services to start..."
+      sleep 30
+
+      # Health check
+      echo "Running health checks..."
+      for i in 1 2 3 4 5 6; do
+        if curl -f -s http://localhost:5000/api/catalog/products > /dev/null 2>&1; then
+          echo "✅ Deployment successful - health check passed"
+          exit 0
+        fi
+        echo "Health check attempt \$i/6 failed, waiting..."
+        sleep 10
+      done
+
+      echo "❌ Health check failed after deployment"
+      docker logs littleshop-admin --tail 50
+      exit 1
+      EOF
+  environment:
+    name: production
+    url: http://hq.lan
+  rules:
+    - if: '$CI_COMMIT_TAG'
+      when: manual
+  tags:
+    - docker
+
+rollback:vps:
+  stage: deploy
+  image: alpine:latest
+  before_script:
+    - apk add --no-cache openssh-client bash
+    - 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:
+    - echo "Rolling back to previous version"
+    - |
+      ssh -i /tmp/deploy_key -p $VPS_PORT $VPS_USER@$VPS_HOST bash -s << EOF
+      set -e
+      cd /opt/littleshop
+
+      # Pull previous image
+      docker tag localhost:5000/littleshop:previous localhost:5000/littleshop:latest
+
+      # Restart services
+      echo "Restarting with previous version..."
+      docker-compose down
+      docker-compose up -d
+
+      # Health check
+      sleep 30
+      if curl -f -s http://localhost:5000/api/catalog/products > /dev/null 2>&1; then
+        echo "✅ Rollback complete"
+        exit 0
+      else
+        echo "❌ Rollback health check failed"
+        docker logs littleshop-admin --tail 50
+        exit 1
+      fi
+      EOF
+  environment:
+    name: production
+  rules:
+    - if: '$CI_COMMIT_TAG'
+      when: manual
+  tags:
+    - docker

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

docker-compose.production.yml

@@ -0,0 +1,70 @@
+version: '3.8'
+
+services:
+  littleshop-admin:
+    image: localhost:5000/littleshop:latest
+    container_name: littleshop-admin
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:5100:5000"
+
+    environment:
+      - ASPNETCORE_ENVIRONMENT=Production
+      - ASPNETCORE_URLS=http://+:5000
+      - DOTNET_ENVIRONMENT=Production
+      - DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=0
+      - DOTNET_RUNNING_IN_CONTAINER=true
+      - DOTNET_USE_POLLING_FILE_WATCHER=true
+      - ASPNETCORE_FORWARDEDHEADERS_ENABLED=true
+
+      # JWT Configuration (from .env - NO defaults)
+      - Jwt__Key=${JWT_SECRET_KEY}
+      - Jwt__Issuer=LittleShop-Production
+      - Jwt__Audience=LittleShop-Production
+      - Jwt__ExpiryInHours=24
+
+      # SilverPay Integration (from .env - NO defaults)
+      - SilverPay__BaseUrl=${SILVERPAY_URL}
+      - SilverPay__ApiKey=${SILVERPAY_API_KEY}
+      - SilverPay__WebhookSecret=${SILVERPAY_WEBHOOK_SECRET}
+      - SilverPay__DefaultWebhookUrl=${SILVERPAY_WEBHOOK_URL}
+      - SilverPay__AllowUnsignedWebhooks=false
+
+      # Database Configuration
+      - ConnectionStrings__DefaultConnection=Data Source=/app/data/littleshop-production.db
+
+    volumes:
+      - littleshop_data:/app/data
+      - littleshop_uploads:/app/wwwroot/uploads
+      - littleshop_logs:/app/logs
+
+    networks:
+      - littleshop-network
+
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5000/api/catalog/products"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+volumes:
+  littleshop_data:
+    driver: local
+  littleshop_uploads:
+    driver: local
+  littleshop_logs:
+    driver: local
+
+networks:
+  littleshop-network:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.21.0.0/16