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:**
- ✅ CalVer versioning (YYYY.MM.BUILD) via shared `cal/gitea-actions/calver` action
- ✅ Docker build + push to Docker Hub
- ✅ Discord notifications via shared `cal/gitea-actions/discord-notify` action
- ✅ Git tagging via shared `cal/gitea-actions/gitea-tag` action
- ✅ Build caching (registry-based)
- ✅ Multi-tag strategy (latest, version, version+sha, dev)

**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

### Projects Using Shared Actions
All use `cal/gitea-actions` composite actions (CalVer, git tagging, Discord notify):

| Project | Workflow | Type |
|---------|----------|------|
| major-domo-database | `docker-build.yml` | Docker build + push |
| paper-dynasty-discord | `docker-build.yml` | Docker build + push |
| paper-dynasty-database | `build.yml` | Docker build + push |
| major-domo-v2 | `docker-build.yml` | Docker build + push |
| vagabond-rpg-foundryvtt | `deploy.yml` | Build + rsync deploy |

### Lessons Learned
- Runner `GITEA_INSTANCE_URL` must use internal IP, not public domain (host mismatch breaks auth)
- `DEFAULT_ACTIONS_URL=self` + short-form refs for local actions, full URLs for GitHub actions
- `REQUIRE_SIGNIN_VIEW=false` is safe — only public repos are exposed, private repos stay locked
- Registry-based Docker build cache (`type=registry`) requires Docker Hub login on every build
- Manual deploy preferred for production Discord bots (health checks needed before auto-deploy)

## 🔧 Common Tasks

### Create New Project Workflow
```bash
cd /path/to/your/repo
mkdir -p .gitea/workflows

# Copy from an existing project (e.g., major-domo-database)
cp /mnt/NV2/Development/major-domo/database/.gitea/workflows/docker-build.yml \
   .gitea/workflows/docker-build.yml

# Customize:
# - Replace Docker Hub image name (manticorum67/your-project)
# - Replace project title in Discord notifications
# - Add repo secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN, DISCORD_WEBHOOK
#
# Action reference rules (DEFAULT_ACTIONS_URL=self):
# - Local actions: short form (cal/gitea-actions/calver@main)
# - GitHub actions: full URL (https://github.com/actions/checkout@v4)
```

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

### CalVer version looks wrong
- CalVer is auto-generated from git tags (YYYY.MM.BUILD)
- BUILD number counts tags in the current month
- Ensure `fetch-depth: 0` in checkout step (needs full tag history)

### 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-18

---

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