littleshop/.gitea/workflows/README.md

Gitea Actions CI/CD Pipeline

This directory contains Gitea Actions workflows for automated building, testing, and deployment of LittleShop.

Workflows

1. Build and Deploy (build-and-deploy.yml)

Triggers:

• Push to main branch → Automatic deployment to production
• Push to development branch → Deployment to development environment
• Push tags (e.g., v1.0.0) → Tagged release with manual deployment option
• Manual trigger via Gitea Actions UI

Jobs:

build-littleshop

• Builds LittleShop Docker image
• Tags with commit SHA and latest
• Uploads image as artifact for deployment

build-telebot

• Builds TeleBot Docker image
• Tags with commit SHA and latest
• Uploads image as artifact for deployment

deploy-production

• Requires: Both build jobs to complete
• Runs: On push to main branch or tagged releases
• Environment: production
• Steps:
  1. Downloads built Docker images
  2. Sets up SSH connection to VPS
  3. Transfers images to production server
  4. Tags images and pushes to local Docker registry
  5. Stops existing containers
  6. Applies database migrations (if present in LittleShop/Migrations/*.sql)
  7. Starts new containers with updated images
  8. Runs health checks
  9. Logs deployment status

deploy-development

• Requires: Both build jobs to complete
• Runs: On push to development branch
• Environment: development
• Placeholder for development deployment configuration

2. Rollback (rollback.yml)

Triggers:

• Manual trigger only via Gitea Actions UI

Inputs:

• environment (required): Choose between production or development
• version (optional): Specific version tag to rollback to (defaults to previous)

Behavior:

1. Connects to VPS via SSH
2. Tags specified version (or previous tag) as latest
3. Stops current containers
4. Starts containers with rolled-back version
5. Runs health checks
6. Logs rollback status

Required Secrets

Configure these secrets in your Gitea repository settings:

VPS Connection

• VPS_HOST - VPS hostname or IP address (e.g., srv1002428.hstgr.cloud)
• VPS_PORT - SSH port (e.g., 2255)
• VPS_USER - SSH username (e.g., sysadmin)
• VPS_SSH_KEY - Private SSH key for authentication (Base64 encoded not required)

Example Secret Configuration

Navigate to: Repository → Settings → Secrets

VPS_HOST: srv1002428.hstgr.cloud
VPS_PORT: 2255
VPS_USER: sysadmin
VPS_SSH_KEY: -----BEGIN OPENSSH PRIVATE KEY-----
<your-private-key-here>
-----END OPENSSH PRIVATE KEY-----

Environment Configuration

Production Environment

Configure in Gitea: Repository → Settings → Environments → New Environment

• Name: production
• URL: https://admin.dark.side
• Protection Rules:
  • Require approval for deployments (optional)
  • Restrict to main branch only

Development Environment

• Name: development
• URL: Your development server URL
• Protection Rules:
  • Allow development branch deployments

Database Migrations

The deployment workflow automatically applies SQLite migrations if present.

Migration Location: LittleShop/Migrations/*.sql

Migration Process:

1. Checks for *.sql files in the Migrations directory
2. Creates automatic backup before each migration: littleshop-production.db.backup-YYYYMMDD-HHMMSS
3. Applies each migration file sequentially
4. Logs migration status

Migration File Format:

-- Migration: Add CustomerDataRetention field
-- Date: 2025-11-14

ALTER TABLE Customers ADD COLUMN DataRetentionDate DATETIME NULL;
CREATE INDEX IF NOT EXISTS IX_Customers_DataRetentionDate ON Customers(DataRetentionDate);

Health Checks

After each deployment, the workflow performs health checks:

• Endpoint: http://localhost:5100/api/catalog/products
• Attempts: 6 attempts with 10-second intervals
• Timeout: 60 seconds total
• On Failure: Displays last 50 lines of container logs and exits with error code

Deployment Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Gitea Actions Runner                    │
│  ┌────────────┐           ┌────────────┐                    │
│  │  Build     │           │  Build     │                    │
│  │ LittleShop │           │  TeleBot   │                    │
│  └─────┬──────┘           └─────┬──────┘                    │
│        │                        │                            │
│        └────────┬───────────────┘                            │
│                 ▼                                            │
│        ┌────────────────┐                                    │
│        │  Upload Images │                                    │
│        │  as Artifacts  │                                    │
│        └────────┬───────┘                                    │
└─────────────────┼────────────────────────────────────────────┘
                  │
                  │ SSH Transfer
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                    Production VPS                            │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Local Docker Registry (localhost:5000)                │ │
│  │  - littleshop:latest, littleshop:<sha>                 │ │
│  │  - telebot:latest, telebot:<sha>                       │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                               │
│  ┌────────────────┐  ┌────────────────┐                     │
│  │  LittleShop    │  │  TeleBot       │                     │
│  │  Container     │  │  Container     │                     │
│  │  Port: 5100    │  │  Port: 5010    │                     │
│  └────────┬───────┘  └────────┬───────┘                     │
│           │                   │                              │
│  ┌────────┴───────────────────┴────────┐                    │
│  │  Docker Networks:                   │                    │
│  │  - littleshop_littleshop-network    │                    │
│  │  - silverpay_silverpay-network      │                    │
│  └─────────────────────────────────────┘                    │
│                                                               │
│  ┌─────────────────────────────────────┐                    │
│  │  Nginx Proxy Manager                │                    │
│  │  https://admin.dark.side            │                    │
│  └─────────────────────────────────────┘                    │
└───────────────────────────────────────────────────────────────┘

Local Testing

To test workflows locally before pushing:

# Install act (GitHub/Gitea Actions local runner)
# For WSL/Linux:
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Run workflow locally
act -W .gitea/workflows/build-and-deploy.yml

# Run specific job
act -W .gitea/workflows/build-and-deploy.yml -j build-littleshop

Troubleshooting

Deployment Fails During Migration

Symptom: Deployment fails with SQLite error

Solution:

1. Check migration file syntax
2. Manually test migration:

   ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
   cd /opt/littleshop
   docker exec -it littleshop sqlite3 /app/data/littleshop-production.db
   

3. Restore from backup if needed:

   docker cp littleshop:/app/data/littleshop-production.db.backup-YYYYMMDD-HHMMSS \
     /app/data/littleshop-production.db
   

Health Check Fails After Deployment

Symptom: "Health check failed after deployment"

Solution:

1. Check container logs:

   ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
   docker logs littleshop --tail 100
   docker logs telebot-service --tail 100
   

2. Verify network connectivity:

   docker exec littleshop curl -I http://localhost:5000/api/catalog/products
   

3. Check if database is accessible:

   docker exec littleshop ls -lh /app/data/
   

SSH Connection Issues

Symptom: "Permission denied" or "Connection refused"

Solution:

1. Verify SSH key is correct in repository secrets
2. Check SSH port and firewall rules:

   ssh -v -p 2255 sysadmin@srv1002428.hstgr.cloud
   

3. Ensure SSH key has correct permissions (600)

Docker Network Not Found

Symptom: "network not found: silverpay_silverpay-network"

Solution:

1. Create missing networks:

   docker network create silverpay_silverpay-network
   docker network create littleshop_littleshop-network
   

2. Verify docker-compose.yml network configuration

Workflow Optimization Tips

1. Faster Builds: Use BuildKit caching

   - name: Build with cache
     uses: docker/build-push-action@v5
     with:
       cache-from: type=gha
       cache-to: type=gha,mode=max
   

2. Parallel Jobs: Build jobs run in parallel by default

3. Artifact Retention: Artifacts kept for 1 day to save storage

4. Docker Layer Caching: Enabled via BuildKit

Migration from GitLab CI/CD

This workflow replaces the previous .gitlab-ci.yml configuration.

Key Differences:

• Uses Gitea Actions (GitHub Actions syntax) instead of GitLab CI/CD
• Artifacts stored in Gitea instead of GitLab
• Environment protection rules configured in Gitea UI
• Same deployment logic and VPS configuration

No Changes Required On VPS:

• Deployment scripts identical
• Docker network configuration unchanged
• Database migration process identical
• Health check endpoints unchanged