terraform-docker-renovate/QUICKSTART.md

Renovate Quick Start Guide

This is a quick reference for getting Renovate up and running with Gitea.

Prerequisites Checklist

• Gitea instance running and accessible
• Docker host accessible via TCP
• Traefik network exists (docker network ls | grep traefik_network)
• HashiCorp Vault with AppRole authentication
• DNS server configured (optional, for CNAME records)

Step 1: Create Renovate Bot User in Gitea

1. Log into your Gitea instance
2. Create a new user:
   • Username: renovate-bot
   • Email: renovate-bot@bsdserver.nl
   • Full Name: Renovate Bot
3. Complete the registration

Step 2: Generate Personal Access Token

1. Log in as renovate-bot
2. Navigate to: Settings → Applications → Generate New Token
3. Token name: Renovate Token
4. Select these scopes:
   • ☑️ repo (Read and Write)
   • ☑️ user (Read)
   • ☑️ issue (Read and Write)
   • ☑️ organization (Read)
5. Generate and save the token securely

Step 3: Configure terraform.tfvars

Edit terraform.tfvars and update:

# Renovate Configuration
domain              = "bsdserver.nl"
role_id             = "your-vault-role-id"
secret_id           = "your-vault-secret-id"

# Gitea Configuration
renovate_endpoint   = "https://gitea.bsdserver.nl/api/v1/"
renovate_token      = "your-gitea-token-from-step-2"
renovate_git_author = "Renovate Bot <renovate-bot@bsdserver.nl>"
renovate_username   = "renovate-bot"

Important: Replace your-gitea-token-from-step-2 with the actual token from Step 2.

Step 4: Deploy Renovate

# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Deploy
terraform apply

Type yes when prompted to confirm.

Step 5: Verify Deployment

# Check container is running
docker ps | grep renovate

# View logs
docker logs renovate -f

Look for messages like:

• ✅ "Platform: gitea"
• ✅ "Autodiscovering repositories"
• ✅ "Repository: owner/repo"

Step 6: Add Renovate to a Test Repository

1. Navigate to a test repository in Gitea
2. Add renovate-bot as a collaborator with Write access
3. Create a new file renovate.json in the repository root:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "assignees": ["@yourusername"],
  "labels": ["renovate"],
  "dependencyDashboard": true
}

4. Commit and push

Step 7: Wait for Onboarding PR

Within a few minutes (depends on your container restart schedule), Renovate will:

1. Scan the repository
2. Create an "onboarding" pull request
3. The PR will explain what Renovate will do

Review and merge the onboarding PR to activate Renovate.

Step 8: Configure Scheduling (Optional)

Choose one of these methods:

Option A: Cron Job

# Add to crontab (runs daily at 2 AM)
crontab -e

# Add this line:
0 2 * * * docker restart renovate

Option B: Gitea Actions

Create .gitea/workflows/renovate.yaml in a repository:

name: Renovate
on:
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:

jobs:
  renovate:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Renovate
        run: docker restart renovate || true

Common Issues

Container Won't Start

Check: Endpoint URL format

# Should end with /api/v1/
docker logs renovate | grep -i endpoint

Fix: Update renovate_endpoint in terraform.tfvars to include /api/v1/

No PRs Being Created

Check: Token permissions

docker logs renovate | grep -i "401\|403\|unauthorized"

Fix: Regenerate token with correct scopes (see Step 2)

Bot Can't Access Repositories

Check: Bot user is added as collaborator

• Go to repository Settings → Collaborators
• Add renovate-bot with Write access

Or: Enable autodiscovery

• Set renovate_autodiscover = true in terraform.tfvars

What Happens Next?

Once activated, Renovate will:

1. 🔍 Scan repositories for dependencies
2. 📊 Create a dependency dashboard issue
3. 🔄 Monitor for updates to:
   • Docker images
   • Terraform modules and providers
   • npm packages
   • pip packages
   • And many more...
4. 🚀 Create PRs when updates are available
5. ✅ Auto-merge (if configured) when CI passes

Example Repository Types

Docker Compose Repository

Add this to renovate.json:

{
  "extends": ["config:recommended"],
  "docker-compose": {
    "enabled": true
  }
}

Terraform Repository

Add this to renovate.json:

{
  "extends": ["config:recommended"],
  "terraform": {
    "enabled": true
  }
}

Python Repository

Add this to renovate.json:

{
  "extends": ["config:recommended"],
  "pip_requirements": {
    "enabled": true
  }
}

Useful Commands

# View container logs
docker logs renovate -f

# Check last 100 lines
docker logs renovate --tail 100

# Restart Renovate (triggers a new run)
docker restart renovate

# Check config file
docker exec renovate cat /usr/src/app/config.js

# View container environment
docker exec renovate env | grep RENOVATE

# Check volumes
docker volume ls | grep renovate

Next Steps

1. ✅ Add Renovate to more repositories
2. ✅ Configure auto-merge rules
3. ✅ Set up dependency dashboards
4. ✅ Configure scheduling
5. ✅ Monitor PRs and merge updates
6. ✅ Integrate with CI/CD pipelines

Getting Help

• 📖 README.md: Comprehensive documentation
• 🔄 MIGRATION_GUIDE.md: Detailed migration steps
• 📝 CHANGELOG.md: Version history
• 🌐 Renovate Docs: https://docs.renovatebot.com/
• 🔗 Gitea Platform: https://docs.renovatebot.com/modules/platform/gitea/

Quick Tips

1. Start Small: Test on one repository first
2. Review PRs: Don't auto-merge everything initially
3. Use Labels: Tag Renovate PRs for easy filtering
4. Schedule Wisely: Avoid peak hours
5. Monitor Logs: Check for errors regularly
6. Pin Versions: Use semantic versioning, not latest

---

That's it! You now have Renovate automatically managing dependencies across your repositories. 🎉