Initial commit: Complete NodeJS-native setup

- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
2025-09-06 01:42:48 -07:00
commit e48adbcb00
159 changed files with 24405 additions and 0 deletions
--- a/.gitea/README.md
+++ b/.gitea/README.md
@@ -0,0 +1,236 @@
+# 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