littleshop/GITLAB-CI-DEPLOYMENT.md

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:

   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:

   ssh-copy-id -i ~/.ssh/littleshop_deploy_key.pub -p 2255 sysadmin@srv1002428.hstgr.cloud
   

3. Test SSH access:

   ssh -i ~/.ssh/littleshop_deploy_key -p 2255 sysadmin@srv1002428.hstgr.cloud "echo 'SSH key works!'"
   

4. Base64 encode the private key:

   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:

   git add .
   git commit -m "Add new feature"
   git push origin main
   

2. Create a version tag:

   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:

   # 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:

# 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

# 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:

   ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
   

2. Edit .env file (use a secure editor):

   nano /opt/littleshop/.env
   

3. Restart services to apply changes:

   cd /opt/littleshop
   docker-compose restart
   

4. Verify service is healthy:

   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:

   # 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:

   ssh hostinger "df -h"
   

Health Check Fails

Symptom: Deployment completes but health check fails

Solutions:

1. Check container logs:

   ssh hostinger "docker logs littleshop-admin --tail 50"
   

2. Verify .env file has all required variables:

   ssh hostinger "cat /opt/littleshop/.env"
   

3. Test health endpoint manually:

   ssh hostinger "curl -v http://localhost:5100/api/catalog/products"
   

4. Check database file permissions:

   ssh hostinger "ls -la /opt/littleshop/data/"
   

Container Won't Start

Symptom: Container exits immediately or won't start

Solutions:

1. Check environment variables:

   docker exec littleshop-admin env | grep -E "(JWT|SILVERPAY)"
   

2. Verify database connectivity:

   docker exec littleshop-admin ls -la /app/data/
   

3. Review startup logs:

   docker logs littleshop-admin
   

---

Monitoring & Maintenance

Health Checks

The application includes built-in health checks:

# 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):

# 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:

#!/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