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.

```bash
# 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:**
```bash
vault kv patch secret/renovate renovate_token="NEW_TOKEN_HERE"
```

## Step 4: Configure terraform.tfvars

Edit `terraform.tfvars` and update only these values:

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

```bash
# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Deploy
terraform apply
```

Type `yes` when prompted to confirm.

## Step 6: Verify Deployment

```bash
# 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:
   ```bash
   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:

```json
{
  "$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

```bash
# 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:

```yaml
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
```bash
# 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
```bash
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`:

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

### Terraform Repository

Add this to `renovate.json`:

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

### Python Repository

Add this to `renovate.json`:

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

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

```bash
# 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. 🎉