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