plex-playlist/docs/RENOVATE_SETUP_GUIDE.md

# Renovate Bot Setup Guide

## Overview

Renovate is an automated dependency update tool that creates pull requests to keep your project dependencies up to date. This guide covers setting up Renovate for the plex-playlist project with optimal configuration.

## Setup Options

### Option 1: GitHub App (Recommended for GitHub)

1. **Install Renovate App**:
   - Go to [Renovate GitHub App](https://github.com/apps/renovate)
   - Click "Install" and select your repository
   - Choose repository access (single repo or organization-wide)

2. **Configure Repository Access**:
   - Select the `plex-playlist` repository
   - Grant necessary permissions (read/write to repository, pull requests, issues)

3. **Initial Configuration**:
   - Renovate will automatically detect the `renovate.json` file
   - Creates an onboarding PR to explain the configuration
   - Review and merge the onboarding PR to activate

### Option 2: Self-Hosted (For Gitea/Custom Git Servers)

Since your project uses `dogar.darkhelm.org` (Gitea), you'll need to run Renovate as a service:

#### Docker-based Self-Hosted Setup

1. **Create Renovate Configuration**:

```bash
# Create renovate directory
mkdir -p ~/.config/renovate
```

2. **Create Renovate Bot Token**:
   - **For Organization Repositories**: See detailed guide → **[Gitea Token Setup](GITEA_TOKEN_SETUP.md)**
   - Required permissions: `repository` (Read/Write), `issue` (Read/Write), `organization` (Read), `user` (Read)
   - Save token securely for next step

3. **Create Environment Configuration**:

```bash
# ~/.config/renovate/config.js
module.exports = {
  platform: 'gitea',
  endpoint: 'https://dogar.darkhelm.org/api/v1',
  token: process.env.RENOVATE_TOKEN,
  gitAuthor: 'Renovate Bot <renovate@darkhelm.org>',
  repositories: ['DarkHelm.org/plex-playlist'],
  onboarding: false, // Skip onboarding PR
  requireConfig: 'required' // Use existing renovate.json
};
```

4. **Run with Docker**:

```bash
# Run Renovate Bot
docker run --rm \
  -e RENOVATE_TOKEN="your_gitea_token_here" \
  -v ~/.config/renovate/config.js:/usr/src/app/config.js \
  renovate/renovate:latest
```

#### Scheduled Automation

Create a systemd timer or cron job to run Renovate periodically:

```bash
# /etc/cron.d/renovate-bot
# Run Renovate every Monday at 8 AM
0 8 * * 1 root docker run --rm -e RENOVATE_TOKEN="$RENOVATE_TOKEN" -v ~/.config/renovate/config.js:/usr/src/app/config.js renovate/renovate:latest
```

### Option 3: CI/CD Integration

Add Renovate to your existing Gitea Actions workflow:

```yaml
# .gitea/workflows/renovate.yml
name: Renovate
on:
  schedule:
    - cron: '0 8 * * 1' # Monday 8 AM
  workflow_dispatch: # Manual trigger

jobs:
  renovate:
    runs-on: ubuntu-act
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Renovate
        uses: renovatebot/github-action@v40.3.2
        with:
          configurationFile: renovate.json
          token: ${{ secrets.RENOVATE_TOKEN }}
        env:
          RENOVATE_PLATFORM: gitea
          RENOVATE_ENDPOINT: https://dogar.darkhelm.org/api/v1
```

## Configuration Explanation

### Key Features of Our Configuration

1. **Smart Scheduling**:
   - Regular updates: Weekday mornings before 9 AM
   - Security updates: Any time
   - Grouped updates: Monday mornings

2. **Automerge Strategy**:
   - **Auto**: Minor/patch updates for trusted packages (types, linting tools)
   - **Manual**: Major updates, Docker base images, security fixes

3. **Grouping**:
   - **Python dev tools**: ruff, pytest, mypy, etc.
   - **Frontend dev tools**: eslint, prettier, typescript, etc.
   - **Docker base images**: ubuntu, python, node versions

4. **Custom Managers**:
   - Detects Python/Node versions in Dockerfiles
   - Updates base image versions automatically

### Package Manager Support

Our configuration handles:

- **Python (uv)**: `backend/pyproject.toml`
- **Node.js (Yarn)**: `frontend/package.json` + `frontend/yarn.lock`
- **Docker**: All `Dockerfile.*` files
- **GitHub Actions**: `.gitea/workflows/*.yml` (if using actions)

## Testing the Configuration

### 1. Validate Configuration

```bash
# Install Renovate CLI for testing
npm install -g renovate

# Validate configuration
renovate-config-validator renovate.json

# Dry run (shows what would be updated)
renovate --dry-run --log-level=debug DarkHelm.org/plex-playlist
```

### 2. Expected Behavior

Once active, Renovate will:

1. **Scan Dependencies**: Daily check for updates
2. **Create PRs**: Individual PRs for each update group
3. **Auto-merge**: Safe updates (minor/patch) merge automatically
4. **Security Alerts**: Immediate PRs for vulnerability fixes
5. **Dependency Dashboard**: Issue with update status overview

### 3. Integration with CI/CD

Renovate PRs will trigger your existing CI/CD pipeline:
- Build and test in Docker containers
- Run full quality gates (linting, type checking, tests)
- Only merge if all checks pass

## Monitoring and Maintenance

### Dashboard

Renovate creates a "Dependency Dashboard" issue showing:
- Pending updates
- Failed PRs
- Ignored dependencies
- Configuration errors

### Logs and Debugging

For self-hosted setup:
```bash
# Run with debug logging
docker run --rm \
  -e LOG_LEVEL=debug \
  -e RENOVATE_TOKEN="your_token" \
  -v ~/.config/renovate/config.js:/usr/src/app/config.js \
  renovate/renovate:latest
```

### Common Issues

1. **Node.js Version Compatibility**:
   - Renovate 41+ requires Node.js 24.10.0+ or 22.13.0+
   - Use `renovate@40.3.2` for older Node.js versions
   - Our CI workflow automatically handles this

2. **Token Permissions**: Ensure Gitea token has repo write access
3. **Rate Limiting**: Adjust `prHourlyLimit` if hitting API limits
4. **Large Updates**: Major version updates may need manual review
5. **Docker Registry**: Ensure base image updates don't break builds

### Quick Validation

For basic JSON validation without installing Renovate:
```bash
# Quick syntax check (no Renovate installation needed)
./scripts/quick-renovate-check.sh

# Full validation (requires Renovate installation)
./scripts/validate-renovate.sh
```

## Security Considerations

1. **Token Security**: Store Renovate token in secrets management
2. **Branch Protection**: Ensure main branch requires PR reviews
3. **Automerge Limits**: Only automerge trusted, low-risk updates
4. **Vulnerability Alerts**: Enable immediate security update PRs

## Advanced Configuration

### Custom Rules Example

```json
{
  "packageRules": [
    {
      "description": "Pin exact versions for critical packages",
      "matchPackageNames": ["fastapi", "@types/node"],
      "rangeStrategy": "pin"
    },
    {
      "description": "Ignore beta/alpha releases",
      "matchPackagePatterns": [".*"],
      "ignoreUnstable": true
    }
  ]
}
```

### Notification Integration

```json
{
  "notifications": [
    {
      "platform": "slack",
      "endpoint": "https://hooks.slack.com/services/...",
      "channels": ["#dev-notifications"]
    }
  ]
}
```

## Next Steps

1. **Choose Setup Method**: GitHub App (if on GitHub) or self-hosted (for Gitea)
2. **Generate API Token**: Create token with appropriate permissions
3. **Test Configuration**: Run dry-run to verify setup
4. **Monitor First Updates**: Review initial PRs to ensure proper operation
5. **Adjust Settings**: Fine-tune automerge rules based on project needs

---

**Related Documentation**:
- [Renovate Official Docs](https://docs.renovatebot.com/)
- [Configuration Options](https://docs.renovatebot.com/configuration-options/)
- [Package Rules](https://docs.renovatebot.com/configuration-options/#packagerules)