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:

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

```bash
# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Deploy
terraform apply
```

Type `yes` when prompted to confirm.

## Step 5: Verify Deployment

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

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

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

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