Renovate mit Docker installieren: Automatisierter Dependency-Update-Bot für GitHub, GitLab und Gitea

Veraltete Abhängigkeiten sind einer der häufigsten Einfallstore für Sicherheitslücken – und gleichzeitig die Aufgabe, die am leichtesten automatisierbar ist. Renovate (21.800 GitHub-Sterne, AGPL-3.0, gepflegt von Mend.io) ist ein Open-Source-Bot, der Repositories nach veralteten Dependencies durchsucht und automatisch Pull Requests mit dem jeweiligen Update öffnet. Er unterstützt über 90 Paketmanager – von npm und pip über Maven, Gradle und Go bis hin zu Docker-Images selbst – und läuft mit GitHub, GitLab, Gitea, Forgejo, Bitbucket und Azure DevOps. Als self-hosted Docker-Container brauchst du weder eine Datenbank noch Redis: Renovate startet, arbeitet seine Repos ab und beendet sich wieder. Das Scheduling übernimmt ein klassischer Cron-Job auf dem Host.

Voraussetzungen

1. Linux-Host, VM oder NAS mit Docker Engine >= 20.10 und dem Compose-Plugin v2 (Befehl: docker compose). Noch nicht installiert? Lies zuerst die Grundlage: Docker und Docker Compose auf Linux installieren.
2. Personal Access Token (PAT) eines dedizierten Renovate-Bot-Accounts auf der Zielplattform (GitHub, GitLab oder Gitea) mit Schreibrecht auf Repositories und Issues.
3. Optional, aber empfohlen: zweiter GitHub.com-PAT (RENOVATE_GITHUB_COM_TOKEN) – auch wenn du kein GitHub nutzt, bezieht Renovate Changelogs und Tool-Downloads von github.com. Ohne Token gilt das anonyme Rate-Limit von 60 Anfragen pro Stunde.
4. Internetzugang des Docker-Hosts (für API-Aufrufe und Tool-Downloads beim Standard-Image).
5. Cron oder systemd auf dem Host für die periodische Ausführung.
6. Ressourcen: RAM-Bedarf variiert je nach Anzahl der Repositories; für einen typischen KMU-Einsatz mit 10–20 Repos reichen 512 MB. CPU-Last entsteht nur während des Laufs.

Schritt 1: Eckdaten und Image-Übersicht

Bevor du Dateien anlegst, lohnt ein Blick auf die wichtigsten Parameter. Renovate bietet zwei Image-Varianten mit unterschiedlichem Trade-off zwischen Größe und Startgeschwindigkeit:

Verifizieren: Rufe docker compose version auf – die Ausgabe muss „Docker Compose version v2.x.x" zeigen. Mit docker info prüfst du, ob der Docker-Daemon läuft.

Schritt 2: Projektordner und config.js anlegen

Alle Renovate-Dateien kommen in einen gemeinsamen Ordner. Das Unterverzeichnis renovate-config/ wird als Bind-Mount in den Container gemountet; dort sucht Renovate beim Start nach der config.js. Wichtig: Renovate läuft im Container als User 12021 (nicht root) – der Ordner muss für diesen User lesbar sein.

mkdir -p /opt/renovate/renovate-config
cd /opt/renovate
# Verzeichnisrechte für Container-User 12021 setzen
chmod 755 /opt/renovate/renovate-config

Lege jetzt die config.js an. Diese Minimal-Konfiguration aktiviert Renovate, setzt das Automerge-Verhalten und empfiehlt sich als Ausgangspunkt:

cat > /opt/renovate/renovate-config/config.js << 'EOF'
module.exports = {
  // Plattform und Repos werden per Umgebungsvariable gesetzt
  // Hier kannst du globales Verhalten definieren

  // Zeitplan: PRs nur montags und donnerstags
  schedule: ['before 6am on monday', 'before 6am on thursday'],

  // Automatisch Sicherheitslücken-PRs priorisieren
  vulnerabilityAlerts: {
    labels: ['security'],
    automerge: false,
  },

  // Limit gleichzeitig offener PRs pro Repo
  prConcurrentLimit: 5,

  // Trockenlauf-Modus: auf true setzen zum Testen (keine echten PRs)
  // dryRun: 'full',
};
EOF

Alternativ kann jedes Repository seine eigene renovate.json enthalten (z. B. mit "extends": ["config:base"]), die diese globale Konfiguration überschreibt.

Verifizieren: Mit ls -la /opt/renovate/renovate-config/ muss die config.js sichtbar sein. Prüfe auf korrekte JavaScript-Syntax – geschweifte Klammern und Kommas müssen vollständig sein.

Schritt 3: .env mit Zugangsdaten anlegen

Secrets gehören in eine .env-Datei, nicht in die compose.yaml. Passe die Werte für deine Plattform an:

# /opt/renovate/.env
# --- Pflichtfelder ---
# PAT des Renovate-Bot-Accounts auf der Zielplattform
RENOVATE_TOKEN=ghp_deinGitHubTokenHier

# Zielplattform: github | gitlab | gitea
RENOVATE_PLATFORM=github

# --- Für GitLab / Gitea: API-Endpunkt (ohne /api/v1-Pfad)
# RENOVATE_ENDPOINT=https://gitea.example.com

# --- Repos festlegen (oder AUTODISCOVER nutzen)
RENOVATE_REPOSITORIES=deinorg/repo1,deinorg/repo2

# Alternativ: alle zugänglichen Repos automatisch scannen
# RENOVATE_AUTODISCOVER=true

# --- Empfohlen ---
# GitHub.com-Token für Changelogs und Tool-Downloads
RENOVATE_GITHUB_COM_TOKEN=ghp_deinGitHubComTokenHier

# Git-Commit-Autor für PRs
RENOVATE_GIT_AUTHOR=Renovate Bot <renovate@example.com>

# --- Optional ---
LOG_LEVEL=info

Schütze die Datei vor anderen Nutzern:

chmod 600 /opt/renovate/.env

Verifizieren: stat -c "%a %n" /opt/renovate/.env muss 600 /opt/renovate/.env ausgeben.

Schritt 4: compose.yaml erstellen

Wechsle in den Projektordner und lege die compose.yaml an. Da Renovate ein einmaliger Batch-Job ist, steht restart: "no" – das ist entscheidend. Mit restart: always würde Renovate endlos neu starten und sofort Rate-Limits auslösen.

# /opt/renovate/compose.yaml
services:
  renovate:
    image: renovate/renovate:43
    container_name: renovate
    restart: "no"
    env_file:
      - .env
    environment:
      - RENOVATE_PLATFORM=${RENOVATE_PLATFORM:-github}
      - RENOVATE_ENDPOINT=${RENOVATE_ENDPOINT:-}
      - RENOVATE_AUTODISCOVER=${RENOVATE_AUTODISCOVER:-false}
      - RENOVATE_REPOSITORIES=${RENOVATE_REPOSITORIES:-}
      - RENOVATE_GIT_AUTHOR=${RENOVATE_GIT_AUTHOR:-Renovate Bot <renovate@example.com>}
      - RENOVATE_GITHUB_COM_TOKEN=${RENOVATE_GITHUB_COM_TOKEN:-}
      - RENOVATE_BASE_DIR=/tmp/renovate
      - RENOVATE_CACHE_DIR=/tmp/renovate/cache
      - RENOVATE_CONFIG_FILE=/usr/src/app/config.js
      - LOG_LEVEL=${LOG_LEVEL:-info}
    volumes:
      - ./renovate-config:/usr/src/app
      - renovate-data:/tmp/renovate
      - renovate-cache:/tmp/renovate/cache

volumes:
  renovate-data:
  renovate-cache:

Verifizieren: Syntaxprüfung mit docker compose config im Projektordner – die Ausgabe zeigt die aufgelöste Konfiguration ohne Fehlermeldung:

cd /opt/renovate
docker compose config

Schritt 5: Ersten Testlauf durchführen

Da Renovate kein dauerhaft laufender Dienst ist, startest du ihn nicht mit docker compose up -d, sondern mit docker compose run. Beim ersten Lauf empfiehlt es sich, den Trockenlauf-Modus zu aktivieren: Setze dryRun: 'full' in der config.js (Zeile ist als Kommentar vorhanden – entferne das //).

cd /opt/renovate
docker compose run --rm renovate

Der erste Lauf mit dem Standard-Image dauert mehrere Minuten, weil benötigte Tools (npm, poetry, Gradle-Wrapper usw.) heruntergeladen und im Cache-Volume abgelegt werden. Folgeläufe sind deutlich schneller.

Erwartete Ausgabe bei Erfolg (LOG_LEVEL=info):

INFO: Repository started (repository=deinorg/repo1)
INFO: Dependency extraction complete (repository=deinorg/repo1)
INFO: DRY_RUN: Would create PR for package.json upgrade ...
INFO: Repository finished (repository=deinorg/repo1)

Verifizieren: Der Container muss sich nach dem Lauf mit Exit-Code 0 beenden:

docker compose ps --all
# Erwartete Ausgabe:
# NAME       IMAGE                   STATUS
# renovate   renovate/renovate:43    Exited (0) N seconds ago

Bei Exit-Code 1 oder Fehlern wie 401 Unauthorized oder Repository not found: Token-Scopes prüfen (siehe Troubleshooting). Nach erfolgreichem Testlauf das dryRun in der config.js wieder auskommentieren.

Schritt 6: Cron-Job für automatische Läufe einrichten

Renovate braucht ein externes Scheduling – entweder per cron oder systemd-Timer. Der Cron-Weg ist einfacher. Öffne die crontab des root-Users (oder eines dedizierten Users mit Docker-Berechtigung):

crontab -e

Füge folgenden Eintrag ein, um Renovate stündlich zu starten:

# Renovate stündlich um Minute 15 ausführen
15 * * * * cd /opt/renovate && docker compose run --rm renovate >> /var/log/renovate.log 2>&1

Alternativ mit systemd-Timer – Details erklärt die Anleitung systemd-Service selbst erstellen und verwalten sowie Cron und crontab richtig nutzen.

Logrotation für die Renovate-Logdatei einrichten:

cat > /etc/logrotate.d/renovate << 'EOF'
/var/log/renovate.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}
EOF

Verifizieren: Teste den Cron-Eintrag manuell:

cd /opt/renovate && docker compose run --rm renovate
tail -50 /var/log/renovate.log

Nach dem nächsten automatischen Cron-Lauf muss ein neuer Zeitstempel in /var/log/renovate.log erscheinen. Mit docker ps --filter "name=renovate" siehst du laufende oder kürzlich beendete Container.

Schritt 7: Gitea- oder GitLab-Konfiguration

Für self-hosted Plattformen sind zwei zusätzliche Variablen erforderlich. Passe die .env entsprechend an:

Gitea-Beispiel:

RENOVATE_PLATFORM=gitea
RENOVATE_ENDPOINT=https://gitea.example.com
RENOVATE_TOKEN=deinGiteaPAT

Der Gitea-PAT benötigt folgende Scopes: repository (read + write), issue (read + write, ab Gitea 1.20), user (read). Den Endpunkt gibst du ohne den Pfad /api/v1 an – Renovate ergänzt ihn selbst.

GitLab-Beispiel:

RENOVATE_PLATFORM=gitlab
RENOVATE_ENDPOINT=https://gitlab.example.com
RENOVATE_TOKEN=glpat-deinGitLabToken

Wichtig: Eine einzelne Renovate-Instanz bedient immer genau eine Plattform. Wenn du sowohl GitHub als auch Gitea betreibst, richtest du zwei separate Compose-Projekte mit je eigenem Cron-Job ein.

Verifizieren:

cd /opt/renovate
LOG_LEVEL=debug docker compose run --rm renovate 2>&1 | head -50

Erwartete Debug-Ausgabe: INFO: Autodiscovering repositories oder INFO: Repository started (repository=...) – keine ENOTFOUND- oder 401-Fehler.

Schritt 8: Updates und Wartung

Renovate-Updates sind unkompliziert, weil kein laufender Dienst gestoppt werden muss. Ziehe einfach das neue Image, bevor der nächste Cron-Lauf startet:

cd /opt/renovate
docker compose pull
docker compose run --rm renovate

Für automatische Image-Updates empfiehlt sich Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich. Alte Images bereinigen:

docker image prune -f

Verifizieren:

docker image ls renovate/renovate
# Zeigt das neue Image-Datum und die neue Digest-ID

Troubleshooting / Typische Fehler

1. 401 Unauthorized oder Repository not found: Der PAT hat nicht die nötigen Scopes oder ist abgelaufen. Für Gitea: repository (read/write) + issue (read/write) + user (read) prüfen. Für GitHub: repo-Scope. Token in der Plattform-UI neu generieren und in .env ersetzen.
2. RENOVATE_ENDPOINT fehlt bei Gitea/GitLab: Renovate versucht stattdessen die github.com-API anzusprechen und schlägt mit ENOTFOUND oder Plattform-Fehlern fehl. Pflichtfeld setzen: RENOVATE_ENDPOINT=https://gitea.example.com ohne abschließendes / und ohne /api/v1.
3. Container startet sofort neu (Endlosschleife): restart: always oder restart: unless-stopped gesetzt. Korrekt ist restart: "no", da Renovate ein Einmal-Job ist.
4. Erster Lauf sehr langsam (5–15 Minuten): Das Standard-Image lädt beim ersten Lauf npm, poetry, Gradle usw. herunter. Cache-Volume korrekt gemountet? Prüfe mit docker volume ls | grep renovate. Alternativ: renovate/renovate:43-full verwenden (alle Tools vorinstalliert, ~2,4 GB).
5. config.js nicht gefunden / keine Repos verarbeitet: Volume-Mount prüfen: ./renovate-config:/usr/src/app korrekt und config.js liegt darin. Verzeichnisrechte: Container läuft als User 12021, Ordner muss mit chmod 755 lesbar sein.
6. Keine Aktion, Exit-Code 0, aber keine PRs: Entweder RENOVATE_REPOSITORIES ist leer und RENOVATE_AUTODISCOVER=false, oder alle Dependencies sind bereits aktuell. Mit LOG_LEVEL=debug prüfen: INFO: Repository finished – No updates found ist normal; ein sofortiges Ende ohne Repository-Ausgabe deutet auf fehlende Repo-Konfiguration hin.
7. SSL/TLS-Fehler bei self-signed Zertifikaten: NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt als Umgebungsvariable setzen und das CA-Zertifikat per Volume in den Container mounten.
8. Rate-Limit-Fehler von github.com: RENOVATE_GITHUB_COM_TOKEN fehlt. Anonyme Requests sind auf 60/h limitiert. Einen GitHub.com-PAT anlegen und in der .env setzen.

Häufige Fragen

Wie plane ich Renovate-Läufe ohne Cron?

Alternativ zu crontab eignet sich ein systemd-Timer, der genauer geplant werden kann und Fehler ins Journal schreibt. Details zeigt die Anleitung systemd-Service selbst erstellen und verwalten. Für reine Docker-Hosts ist der Cron-Weg mit docker compose run --rm renovate die einfachere Wahl.

Was ist der Unterschied zwischen Standard- und Full-Image?

Das Standard-Image (renovate/renovate:43, ~418 MB) lädt benötigte Paketmanager-Tools beim ersten Lauf herunter und cached sie im Volume. Das Full-Image (renovate/renovate:43-full, ~2,4 GB) enthält alle Tools vorinstalliert, startet schneller und funktioniert auch in Air-Gapped-Umgebungen. Für typische Internet-verbundene Server ist das Standard-Image mit aktiviertem Cache-Volume die bessere Wahl.

Wie teste ich Renovate ohne echte PRs?

Setze dryRun: 'full' in der config.js. Renovate simuliert alle Schritte vollständig, öffnet aber keine PRs und macht keine Commits. Mit LOG_LEVEL=debug siehst du detailliert, welche Updates geplant wären. Nach dem Test die Zeile wieder auskommentieren.

Kann ich mehrere Plattformen gleichzeitig betreiben?

Nein – eine Renovate-Instanz bedient genau eine Plattform (RENOVATE_PLATFORM). Für GitHub und Gitea parallel richtest du zwei separate Compose-Projekte in unterschiedlichen Verzeichnissen ein, jedes mit eigenem PAT, eigener config.js und eigenem Cron-Job.

Wie konfiguriere ich Renovate pro Repository individuell?

Lege im jeweiligen Repository eine renovate.json im Stammverzeichnis an (z. B. mit "extends": ["config:base"]). Diese Repo-Konfiguration wird von Renovate beim Scan automatisch erkannt und überschreibt die globalen Einstellungen aus der config.js. So kannst du für kritische Repos strengere Regeln setzen oder für Test-Repos aggressivere Update-Strategien wählen.

Wie verwalte ich die geöffneten Renovate-PRs?

Renovate dupliziert keine PRs: Beim nächsten Lauf aktualisiert er bestehende offene Renovate-PRs, wenn eine neuere Version verfügbar wurde. Nicht mehr aktuelle PRs schließt er automatisch. Du musst also nur mergen oder ablehnen – Renovate erledigt den Rest.

Fazit

Renovate löst eines der hartnäckigsten Sicherheitsprobleme im Entwicklungsalltag: veraltete Abhängigkeiten, die sich still und leise ansammeln. Als self-hosted Docker-Container ist der Betrieb überraschend schlank – keine Datenbank, kein dauerhaft laufender Prozess, nur ein Cron-Job und eine config.js. Wer 90+ Paketmanager aus einer Hand aktuell halten und PRs automatisch auf GitHub, GitLab oder Gitea eröffnen möchte, hat mit Renovate das richtige Werkzeug. Der einmalige Setup-Aufwand von etwa 20 Minuten amortisiert sich nach dem ersten automatisch erkannten CVE-Fix. Wer noch einen Schritt weiter gehen möchte, findet in der Anleitung Docker-Images auf Schwachstellen scannen mit Trivy ein sinnvolles Ergänzungswerkzeug für aktive CVE-Erkennung direkt im Build-Prozess.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren – die Self-Hosting-Grundlage
2. Docker-Images auf Schwachstellen scannen mit Trivy: CVE-Check und SBOM
3. Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich
4. Gitea mit Docker: eigener Git-Server als GitHub-Alternative
5. Cron und crontab richtig nutzen – die Grundlagen

Offizielle Dokumentation: Renovate Docs – Getting Started: Running | Renovate Docs – Self-Hosting Examples | GitHub – renovatebot/renovate | Docker Hub – renovate/renovate