rxminder/docs/deployment/GITEA_SETUP.md

🦌 Gitea CI/CD Setup Complete!

Your RxMinder app now has comprehensive Gitea Actions CI/CD support! Here's what's been created:

📁 New Files Structure

.gitea/
├── workflows/
│   └── ci-cd.yml              # Main CI/CD workflow
├── docker-compose.ci.yml      # CI-specific compose override
├── gitea-bake.hcl            # Gitea-optimized buildx config
└── README.md                 # Detailed Gitea configuration guide

scripts/
├── gitea-deploy.sh           # Gitea-specific deployment script
└── gitea-helper.sh           # Comprehensive Gitea operations helper

🚀 Quick Start

1. Setup Environment Configuration

# Copy the example environment file and customize
cp .env.example .env

# Edit .env with your registry and configuration:
CONTAINER_REGISTRY=gitea.yourdomain.com
CONTAINER_REPOSITORY=username/rxminder
GITEA_REGISTRY=gitea.yourdomain.com
GITEA_REPOSITORY=username/rxminder

2. Setup Gitea Repository

# Configure in Gitea Repository Settings → Actions

# Required Secrets:
GITEA_TOKEN                   # Personal access token with package write permissions
VITE_COUCHDB_PASSWORD        # CouchDB password
DEPLOYMENT_WEBHOOK_URL       # Optional: deployment notifications

# Repository Variables (optional - will use .env defaults):
GITEA_REGISTRY               # Override registry from .env
VITE_COUCHDB_URL             # http://localhost:5984
VITE_COUCHDB_USER            # admin
APP_BASE_URL                 # http://localhost:8080

3. Local Development with Gitea

# Setup Gitea buildx builder
bun run gitea:setup

# Build for local development
bun run gitea:build-local

# Run tests
bun run gitea:test

# Check status
bun run gitea:status

4. Production Deployment

# Build and push to registry
export GITEA_TOKEN=your_token
export GITEA_REGISTRY=your-gitea.com
export GITEA_REPOSITORY=username/rxminder

bun run gitea:build-prod v1.0.0

# Deploy to production
bun run gitea:deploy production v1.0.0

🔧 Gitea Actions Features

Multi-Platform Builds

• ✅ AMD64 (Intel/AMD processors)
• ✅ ARM64 (Apple Silicon, AWS Graviton)
• ✅ Optimized layer caching
• ✅ Registry-based build cache

Security & Quality

• ✅ Trivy vulnerability scanning
• ✅ Supply chain attestations (SBOM, provenance)
• ✅ Dependency auditing
• ✅ Lint and type checking

Deployment Options

• ✅ Docker Compose deployment
• ✅ Kubernetes deployment
• ✅ Staging environment support
• ✅ Health checks and monitoring

Automation

• ✅ Automatic builds on push/PR
• ✅ Multi-environment deployments
• ✅ Image cleanup and maintenance
• ✅ Deployment notifications

📋 Available Commands

Gitea Helper Script

./scripts/gitea-helper.sh setup          # Setup buildx for Gitea
./scripts/gitea-helper.sh build-local    # Local development build
./scripts/gitea-helper.sh build-multi    # Multi-platform build
./scripts/gitea-helper.sh build-staging  # Staging build
./scripts/gitea-helper.sh build-prod     # Production build
./scripts/gitea-helper.sh test           # Run all tests
./scripts/gitea-helper.sh deploy         # Deploy to environment
./scripts/gitea-helper.sh status         # Show CI/CD status
./scripts/gitea-helper.sh cleanup        # Cleanup builders/images

Package.json Scripts

bun run gitea:setup          # Setup Gitea buildx
bun run gitea:build          # Multi-platform build
bun run gitea:build-local    # Local development
bun run gitea:build-staging  # Staging build
bun run gitea:build-prod     # Production build
bun run gitea:test           # Run tests
bun run gitea:deploy         # Deploy application
bun run gitea:status         # Check status
bun run gitea:cleanup        # Cleanup

🎯 Workflow Triggers

Automatic Triggers

• Push to main/develop: Full build, test, and deploy
• Pull Request: Build, test, and security scan
• Manual dispatch: On-demand deployment

Environment-Specific

• Development: Fast single-platform builds
• Staging: Full testing with staging configs
• Production: Multi-platform with attestations

🔒 Security Features

Image Security

• Vulnerability scanning with Trivy
• Base image security updates
• Minimal attack surface
• Supply chain attestations

Secrets Management

• Gitea-native secrets storage
• Environment-specific variables
• Token rotation support
• Secure registry authentication

📊 Monitoring & Notifications

Health Checks

• Frontend application health
• Database connectivity
• Service dependency checks
• Container resource monitoring

Notifications

• Deployment success/failure alerts
• Security scan results
• Build status updates
• Custom webhook integration

🚀 Next Steps

1. Configure Gitea Repository:

   • Enable Actions in repository settings
   • Add required secrets and variables
   • Configure container registry

2. Set up Gitea Runner:

   • Install and configure Gitea Actions runner
   • Ensure Docker and buildx support
   • Configure appropriate labels

3. Test the Pipeline:

   # Push to trigger the workflow
   git add .
   git commit -m "Setup Gitea CI/CD"
   git push origin main
   

4. Customize for Your Environment:

   • Update registry URLs in .gitea/gitea-bake.hcl
   • Modify deployment targets in scripts/gitea-deploy.sh
   • Configure environment-specific variables

🔄 Migration Notes

• ✅ Fully compatible with existing Docker Buildx setup
• ✅ No breaking changes to development workflow
• ✅ Parallel support with GitHub Actions if needed
• ✅ Easy rollback - simply delete .gitea/ directory

Your RxMinder app is now ready for professional-grade CI/CD with Gitea! 🎉

📞 Troubleshooting

Common Issues:

1. Build failures: Check Gitea runner has Docker buildx
2. Registry push errors: Verify GITEA_TOKEN permissions
3. Deployment issues: Check environment variables and secrets

Debug Commands:

# Check Gitea environment
./scripts/gitea-helper.sh status

# Test local build
./scripts/gitea-helper.sh build-local

# Verify registry login
docker login your-gitea.com