rxminder/.gitea/README.md

# Gitea Actions Configuration for RxMinder

## Environment Variables

### Required Secrets (Configure in Gitea Repository Settings)

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

```bash
# 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

```bash
# 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

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

### 3. Repository Configuration

```bash
# 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

```bash
# 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)

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

### Kubernetes

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

### Staging Environment

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

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

## Troubleshooting

### Common Issues

1. **Build Fails - Buildx Not Available**

```bash
# Ensure Docker Buildx is installed on runner
docker buildx version
```

2. **Registry Push Fails**

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

3. **Deployment Fails**

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

### Debug Commands

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

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