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

Terraform with Docker Containers

If you deploy Docker containers via Terraform and define image versions in your .tf files, Renovate can track those too!

Add annotations to your Terraform code:

locals {
  containers = {
    redis = {
      # renovate: datasource=docker
      image = "redis:8.0.0"
      # ... other settings
    }

    grafana = {
      # renovate: datasource=docker
      image = "grafana/grafana:11.2.0"
      # ... other settings
    }
  }
}

The # renovate: datasource=docker comment tells Renovate to:

1. Parse the image value on the next line
2. Extract the image name and version
3. Create PRs when updates are available

See README.md for more annotation patterns and examples.

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. 🎉