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. Click Generate Token
6. IMMEDIATELY COPY THE TOKEN - You won't be able to see it again!
7. Save the token securely - you'll need it for the next step

Step 3: Store Credentials in HashiCorp Vault

CRITICAL: This module retrieves all Renovate configuration from Vault, NOT from Terraform variables.

# Set your Vault address
export VAULT_ADDR="https://your-vault-server:8200"

# Authenticate to Vault using AppRole
vault login -method=approle \
  role_id=YOUR_VAULT_ROLE_ID \
  secret_id=YOUR_VAULT_SECRET_ID

# Store all Renovate credentials in Vault
vault kv put secret/renovate \
  renovate_platform="gitea" \
  renovate_endpoint="https://gitea.bsdserver.nl/api/v1/" \
  renovate_token="YOUR_TOKEN_FROM_STEP_2" \
  renovate_git_author="Renovate Bot <renovate-bot@bsdserver.nl>" \
  renovate_username="renovate-bot"

# IMPORTANT: Verify the secrets were stored correctly
vault kv get secret/renovate

Expected output:

====== Data ======
Key                    Value
---                    -----
renovate_platform      gitea
renovate_endpoint      https://gitea.bsdserver.nl/api/v1/
renovate_token         <your-token>
renovate_git_author    Renovate Bot <renovate-bot@bsdserver.nl>
renovate_username      renovate-bot

⚠️ Common Mistakes to Avoid:

• ❌ Endpoint without trailing /api/v1/
• ❌ Forgetting the renovate_username key
• ❌ Using wrong Vault path (must be secret/renovate)
• ❌ Token with insufficient scopes

If you need to update the token later:

vault kv patch secret/renovate renovate_token="NEW_TOKEN_HERE"

Step 4: Configure terraform.tfvars

Edit terraform.tfvars and update only these values:

# Vault Authentication (required)
role_id   = "your-vault-role-id"
secret_id = "your-vault-secret-id"

# Optional: Domain configuration
domain = "bsdserver.nl"

Note: renovate_endpoint, renovate_token, renovate_git_author, and renovate_username are NOT Terraform variables - they come from Vault!

Step 5: Deploy Renovate

# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Deploy
terraform apply

Type yes when prompted to confirm.

Step 6: Verify Deployment

# Check container is running
docker ps | grep renovate

# View logs (watch for errors)
docker logs renovate -f

# Check environment variables are set correctly
docker exec renovate env | grep RENOVATE

Expected environment variables:

• ✅ RENOVATE_PLATFORM=gitea
• ✅ RENOVATE_ENDPOINT=https://gitea.bsdserver.nl/api/v1/
• ✅ RENOVATE_TOKEN=<your-token>
• ✅ RENOVATE_GIT_AUTHOR=Renovate Bot <renovate-bot@bsdserver.nl>
• ✅ RENOVATE_USERNAME=renovate-bot
• ✅ RENOVATE_AUTODISCOVER=true

Look for SUCCESS messages in logs:

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

❌ If you see authentication errors:

1. Verify the token is correct in Vault: vault kv get secret/renovate
2. Check the token hasn't expired in Gitea
3. Verify all 5 required keys are in Vault (especially renovate_username)
4. Ensure the endpoint URL ends with /api/v1/

❌ If you see DNS resolution errors (ENOTFOUND):

1. The container cannot resolve your Gitea hostname
2. Check DNS resolution from Docker host:

   dig @192.168.2.2 git.bsdserver.nl
   

3. Configure DNS servers in your deployment:
   • Add to terraform.tfvars: dns_servers = ["192.168.2.2"]
   • Or set in pipeline: TF_VAR_dns_servers='["192.168.2.2"]'
4. Verify the hostname is correct (e.g., git.bsdserver.nl not gitea.bsdserver.nl)
5. Alternative: Use IP address in Vault endpoint instead of hostname

Step 7: 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 8: 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 9: 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. 🎉