claude-home/server-configs/gitea/INDEX.md

# Gitea Configuration & Templates Index

Quick reference for all Gitea-related documentation and templates.

## 📁 Directory Structure

```
/server-configs/gitea/
├── README.md                        # Gitea LXC setup and configuration
├── INDEX.md                         # This file - quick reference
├── deployment-strategies.md         # When/how to deploy (manual vs auto)
├── harbor-registry-setup.md         # Self-hosted Docker registry guide
├── apply_branch_protection.py       # Script for branch protection rules
└── workflow-templates/              # Reusable CI/CD templates
    ├── README.md                    # Template usage guide
    ├── docker-build-template.yml    # Complete Docker CI/CD workflow
    ├── deploy-script-template.sh    # Safe manual deployment script
    └── snippets/                    # Workflow code snippets
        └── auto-deploy-with-rollback.yml
```

## 🚀 Quick Links

### Getting Started
- **New to Gitea Actions?** → Start with `workflow-templates/README.md`
- **Need a workflow?** → Copy `docker-build-template.yml`
- **Want to deploy?** → Read `deployment-strategies.md`

### Templates

#### Docker Build Workflow
**File:** `workflow-templates/docker-build-template.yml`

**Features:**
- ✅ Semantic version validation
- ✅ Docker build + push to Docker Hub
- ✅ Discord notifications
- ✅ Build caching
- ✅ Multi-tag strategy

**Use for:**
- Discord bots
- Web applications
- API services
- Any Dockerized project

#### Manual Deploy Script
**File:** `workflow-templates/deploy-script-template.sh`

**Features:**
- ✅ Pre-deployment checks
- ✅ Confirmation prompts
- ✅ Status verification
- ✅ Log viewing
- ✅ Rollback instructions

**Use when:**
- You want manual control
- Deploying to production
- Testing new deployments

#### Auto-Deploy with Rollback
**File:** `workflow-templates/snippets/auto-deploy-with-rollback.yml`

**Features:**
- ✅ SSH deployment
- ✅ Health checks
- ✅ Automatic rollback
- ✅ Deployment notifications

**Use when:**
- You have good test coverage
- Health checks are implemented
- Downtime is acceptable

### Guides

#### Deployment Strategies
**File:** `deployment-strategies.md`

**Covers:**
- Decision framework (when to auto-deploy)
- 5 levels of deployment automation
- Recommendations by project type
- Safety best practices
- Rollback procedures

**Read this before:** Adding auto-deploy to any project

#### Harbor Registry Setup
**File:** `harbor-registry-setup.md`

**Covers:**
- Self-hosted Docker registry
- Complete Harbor installation
- Integration with Gitea Actions
- Vulnerability scanning
- Backup strategies

**Use when:**
- You want private registries
- You hit Docker Hub rate limits
- You want full control
- Learning opportunity

## 📝 Reference Implementations

### Paper Dynasty Discord Bot
**Status:** ✅ Production
**Date:** 2026-02-04

**Setup:**
- Gitea Actions on LXC 225
- Docker build + push to Docker Hub
- Discord notifications working
- Manual deployment to sba-bots (10.10.0.88)

**Workflow:** Based on `docker-build-template.yml`

**What worked:**
- Semantic version validation
- Multi-tag strategy (latest, version, version+commit)
- Discord webhooks with ISO 8601 timestamps
- GitHub Actions cache for faster builds

**Lessons learned:**
- Timestamp format critical for Discord (ISO 8601)
- Health checks needed before auto-deploy
- Manual deploy preferred for production Discord bots

## 🔧 Common Tasks

### Create New Project Workflow
```bash
cd /path/to/your/repo
mkdir -p .gitea/workflows
cp /path/to/docker-build-template.yml .gitea/workflows/docker-build.yml

# Customize:
# - Replace "yourusername/yourrepo" with your Docker Hub repo
# - Replace "Your Project" in notifications
# - Replace Discord webhook URLs
# - Add secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN
# - Create VERSION file: echo "1.0.0" > VERSION
```

### Add Auto-Deploy (When Ready)
```bash
# Copy auto-deploy snippet
cat workflow-templates/snippets/auto-deploy-with-rollback.yml

# Add to your workflow after build step
# Configure secrets: DEPLOY_SSH_KEY, PRODUCTION_HOST, DEPLOY_USER
```

### Manual Deploy
```bash
# Copy deploy script to your repo
cp workflow-templates/deploy-script-template.sh /path/to/repo/deploy.sh
chmod +x /path/to/repo/deploy.sh

# Customize server details in script
# Then use: ./deploy.sh v1.2.3
```

## 🎓 Learning Path

1. **Start:** Read `workflow-templates/README.md`
2. **Setup:** Deploy Gitea Actions runner (see `README.md`)
3. **First workflow:** Copy `docker-build-template.yml`
4. **Deploy:** Use `deploy-script-template.sh`
5. **Advanced:** Read `deployment-strategies.md`
6. **Optional:** Set up Harbor with `harbor-registry-setup.md`

## 🆘 Troubleshooting

### Version validation failing
- Check VERSION file format: just `1.2.3`
- Ensure semver rules followed
- See template comments for valid bumps

### Docker Hub push failing
- Verify secrets set in Gitea
- Check Docker Hub token permissions
- Ensure repo name matches exactly

### Discord notifications not appearing
- Verify webhook URL still valid
- Check timestamp format (ISO 8601)
- Test webhook manually with curl

### More help
- Check specific template comments
- Read troubleshooting sections in guides
- Review Paper Dynasty as reference implementation

## 📚 External Resources

- [Gitea Actions Docs](https://docs.gitea.io/en-us/usage/actions/overview/)
- [Docker Build Push Action](https://github.com/docker/build-push-action)
- [Semantic Versioning](https://semver.org/)
- [Discord Webhooks](https://discord.com/developers/docs/resources/webhook)
- [Harbor Docs](https://goharbor.io/docs/)

## 🔄 Maintenance

**Update this index when:**
- Adding new templates
- Creating new guides
- Changing directory structure
- Adding reference implementations

**Last updated:** 2026-02-04

---

**Quick search tips:**
- Need deployment guide? → `deployment-strategies.md`
- Need workflow template? → `workflow-templates/`
- Need self-hosted registry? → `harbor-registry-setup.md`
- Need deploy script? → `deploy-script-template.sh`