GITEA_TOKEN                 # Gitea access token for registry access
VITE_COUCHDB_PASSWORD      # CouchDB password (sensitive)
DEPLOYMENT_WEBHOOK_URL     # Optional: webhook for deployment notifications

Repository Variables (Configure in Gitea Repository Settings)

VITE_COUCHDB_URL           # Default: http://localhost:5984
VITE_COUCHDB_USER          # Default: admin
APP_BASE_URL               # Default: http://localhost:8080
VITE_GOOGLE_CLIENT_ID      # Optional: Google OAuth client ID
VITE_GITHUB_CLIENT_ID      # Optional: GitHub OAuth client ID
GITEA_REGISTRY             # Container registry URL (e.g., gitea.yourdomain.com)
GITEA_REPOSITORY           # Repository name (e.g., username/rxminder)

Environment Variables (.env file)

The scripts will automatically load configuration from your .env file. Copy .env.example to .env and customize:

# Copy example and customize
cp .env.example .env

# Key variables for container registry:
CONTAINER_REGISTRY=gitea.yourdomain.com
CONTAINER_REPOSITORY=username/rxminder
GITEA_REGISTRY=gitea.yourdomain.com  # Alternative to CONTAINER_REGISTRY
GITEA_REPOSITORY=username/rxminder       # Alternative to CONTAINER_REPOSITORY

Gitea Actions Features

Workflows

Build & Test: Multi-platform Docker builds with buildx
Security Scanning: Trivy vulnerability scanning
Deployment: Automated deployment to production
Cleanup: Registry and image cleanup

Multi-Platform Support

linux/amd64 (Intel/AMD)
linux/arm64 (ARM64/Apple Silicon)

Caching Strategy

Registry-based caching for faster builds
Layer caching between builds
Dependency caching for Node.js/Bun

Setup Instructions

1. Gitea Server Requirements

# Minimum Gitea version
Gitea >= 1.20.0 with Actions enabled

# Required Gitea features
- Gitea Actions enabled
- Container Registry enabled
- Runners configured

2. Configure Gitea Runner

# .gitea/runners/config.yml (on runner machine)
name: 'rxminder-runner'
labels:
  - 'ubuntu-latest'
  - 'self-hosted'
capabilities:
  - docker
  - buildx

3. Repository Configuration

# 1. Go to Repository Settings → Actions → Secrets
# Add required secrets and variables

# 2. Go to Repository Settings → Packages
# Enable container registry

# 3. Configure runner labels in workflow files if needed

4. Local Testing

# Test Gitea Actions locally with act
# Install: https://github.com/nektos/act

# Test the workflow
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Test specific job
act -P ubuntu-latest=catthehacker/ubuntu:act-latest -j build

Deployment Targets

Docker Compose (Default)

# Deploys using docker-compose.yml
# Suitable for single-server deployments
./scripts/gitea-deploy.sh production

Kubernetes

# Deploys to Kubernetes cluster
# Requires kubectl configured
./scripts/gitea-deploy.sh kubernetes

Staging Environment

# Deploys to staging with different configs
./scripts/gitea-deploy.sh staging

Monitoring & Notifications

Health Checks

Frontend: http://localhost:8080/health
CouchDB: http://localhost:5984/_up

Deployment Notifications

Configure DEPLOYMENT_WEBHOOK_URL to receive notifications:

{
  "text": "✅ RxMinder deployed to production",
  "environment": "production",
  "image": "gitea.example.com/user/rxminder:abc123"
}

Troubleshooting

Common Issues

Build Fails - Buildx Not Available

# Ensure Docker Buildx is installed on runner
docker buildx version

Registry Push Fails

# Check GITEA_TOKEN has package write permissions
# Verify registry URL is correct

Deployment Fails

# Check environment variables are set
# Verify server has Docker/Kubernetes access

Debug Commands

# Check workflow logs in Gitea UI
# Repository → Actions → [Workflow Run]

# Test deployment script locally
./scripts/gitea-deploy.sh production --debug

# Check service status
docker-compose -f docker/docker-compose.yaml ps
docker-compose -f docker/docker-compose.yaml logs

Security Considerations

Image Scanning

Trivy vulnerability scanning in CI
Base image security updates
Dependency audit checks

Secrets Management

Use Gitea secrets for sensitive data
Rotate access tokens regularly
Limit token permissions

Registry Security

Private registry recommended
Image signing (optional)
Regular image cleanup

Performance Optimization

Build Optimization

Multi-stage Dockerfile
Layer caching
Minimal base images

Deployment Optimization

Health checks
Rolling updates
Resource limits

Migration from GitHub Actions

If migrating from GitHub Actions:

Copy workflow structure (already compatible)
Update variable references: github. → gitea.
Configure secrets in Gitea repository settings
Test locally with act before pushing
Update registry URLs if different