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

```bash
# 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   ssh -p 2255 sysadmin@srv1002428.hstgr.cloud
   docker logs littleshop --tail 100
   docker logs telebot-service --tail 100
   ```
2. Verify network connectivity:
   ```bash
   docker exec littleshop curl -I http://localhost:5000/api/catalog/products
   ```
3. Check if database is accessible:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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
   ```yaml
   - 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