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

Veraltete Abhängigkeiten sind ein häufiges Einfallstor für Sicherheitslücken. Renovate (AGPL-3.0, gepflegt von Mend.io) durchsucht Repositories nach veralteten Abhängigkeiten und öffnet Pull Requests mit dem Update. Er unterstützt über 90 Paketmanager, von npm und pip über Maven und Go bis zu Docker-Images, und arbeitet mit GitHub, GitLab, Gitea, Forgejo, Bitbucket und Azure DevOps. Als Docker-Container braucht Renovate weder Datenbank noch Redis: Er startet, arbeitet die Repos ab und beendet sich. Den Zeitplan übernimmt ein 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? Lesen Sie 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. Empfohlen: ein GitHub.com-PAT (RENOVATE_GITHUB_COM_TOKEN), auch ohne GitHub als Plattform. Renovate bezieht Changelogs und Tool-Downloads von github.com, anonym gilt ein Limit von 60 Anfragen pro Stunde.
4. Internetzugang des Docker-Hosts sowie Cron oder systemd für die periodische Ausführung.
5. Ressourcen: x86-64 oder ARM64, 1 CPU-Kern, für 10 bis 20 Repos etwa 512 MB freier RAM während des Laufs und rund 2 GB Speicher für Image und Cache.

Schritt 1: Eckdaten und Image-Übersicht

Renovate bietet zwei Image-Varianten, die sich in Größe und Startzeit unterscheiden:

Verifizieren: docker compose version zeigt „Docker Compose version v2.x.x“, docker info endet ohne Fehler.

Schritt 2: Projektordner und config.js anlegen

Das Unterverzeichnis renovate-config/ wird nach /usr/src/app gemountet, dort sucht Renovate beim Start die config.js. Renovate läuft im Container als User 12021, Ordner und Datei müssen für alle lesbar sein.

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

Legen Sie die config.js an. Diese Minimal-Konfiguration setzt Zeitplan, Sicherheits-PRs und ein PR-Limit:

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

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

Jedes Repository kann zusätzlich eine eigene renovate.json enthalten (siehe Häufige Fragen).

Verifizieren: ls -la /opt/renovate/renovate-config/ zeigt config.js mit -rw-r--r--. Die Syntax prüfen Sie nach Schritt 4 mit dem mitgelieferten Validator: docker compose run --rm --entrypoint renovate-config-validator renovate meldet „Config validated successfully“.

Schritt 3: .env mit Zugangsdaten anlegen

Zugangsdaten gehören in die .env, nicht in die compose.yaml:

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

# Zielplattform: github | gitlab | gitea
RENOVATE_PLATFORM=github

# --- Für eigene Server: API-Endpunkt (siehe Schritt 7)
# RENOVATE_ENDPOINT=https://gitea.example.com

# --- Repos festlegen (oder AUTODISCOVER nutzen)
RENOVATE_REPOSITORIES=meinorg/repo1,meinorg/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_IhrTokenHier

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

# --- Optional ---
LOG_LEVEL=info

Schützen Sie 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

Legen Sie im Projektordner die compose.yaml an. Renovate ist ein Batch-Job, deshalb restart: "no". Mit restart: always startet Renovate endlos neu und löst Rate-Limits aus.

# /opt/renovate/compose.yaml
services:
  renovate:
    image: renovate/renovate:44
    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: docker compose config zeigt die aufgelöste Konfiguration ohne Fehlermeldung:

cd /opt/renovate
docker compose config

Schritt 5: Ersten Testlauf durchführen

Renovate starten Sie mit docker compose run, nicht mit up -d. Aktivieren Sie für den ersten Lauf den Trockenlauf: In der config.js vor dryRun: 'full' das // entfernen.

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

Der erste Lauf dauert mehrere Minuten, weil Tools wie npm oder poetry ins Cache-Volume geladen werden. Erwartete Ausgabe (gekürzt):

INFO: Repository started (repository=meinorg/repo1)
INFO: Dependency extraction complete (repository=meinorg/repo1)
INFO: DRY-RUN: Would create PR: Update dependency ...
INFO: Repository finished (repository=meinorg/repo1)

Im Test lief renovate/renovate:44 (Version 44.148.3): Der Validator bestätigte die config.js. Mit ungültigem Token endete der Lauf mit WARN: github.com token 401 unauthorized, FATAL: Initialization error („Authentication failure“) und Exit-Code 1. Nach erfolgreichem Testlauf dryRun wieder auskommentieren.

Verifizieren: Direkt nach dem Lauf gibt echo $? den Exit-Code aus: 0 bedeutet Erfolg. Wegen --rm bleibt kein Container zurück, docker compose ps --all ist leer. Bei 1 und „Authentication failure“ Token und Scopes prüfen (siehe Troubleshooting).

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

Renovate braucht einen externen Zeitplan per Cron oder systemd-Timer. Öffnen Sie die crontab von root oder eines Users mit Docker-Berechtigung:

crontab -e

Eintrag für einen stündlichen Lauf:

# 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 Logdatei:

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

Verifizieren: Nach dem nächsten Lauf zur Minute 15 zeigt tail -50 /var/log/renovate.log neue Einträge mit „Renovate started“, sudo logrotate -d /etc/logrotate.d/renovate meldet keine Fehler.

Schritt 7: Gitea- oder GitLab-Konfiguration

Für eigene Server setzen Sie Plattform und Endpunkt in der .env:

Gitea-Beispiel:

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

Der Gitea-PAT braucht die Scopes repository (Read and Write), user (Read), ab Gitea 1.20 zusätzlich issue (Read and Write) und organization (Read). Den Endpunkt geben Sie ohne /api/v1 an, Renovate ergänzt ihn. Fehlt RENOVATE_ENDPOINT, verbindet sich Renovate mit gitea.com. Für Forgejo setzen Sie RENOVATE_PLATFORM=forgejo.

GitLab-Beispiel:

RENOVATE_PLATFORM=gitlab
RENOVATE_ENDPOINT=https://gitlab.example.com/api/v4/
RENOVATE_TOKEN=glpat-IhrGitLabToken

Bei GitLab gehört /api/v4/ in den Endpunkt, der Token braucht den Scope api (für reine Trockenläufe genügt read_api). Eine Renovate-Instanz bedient genau eine Plattform (siehe Häufige Fragen).

Verifizieren:

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

Erwartet: eine Zeile DEBUG: Using … endpoint mit Ihrer Server-URL, danach Repository started und keine ENOTFOUND- oder 401-Fehler.

Schritt 8: Updates und Wartung

Für ein Update ziehen Sie das neue Image vor dem nächsten Cron-Lauf:

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

Der Tag :44 hält die Hauptversion fest. Ein Wechsel auf die nächste Hauptversion passiert nur, wenn Sie den Tag in der compose.yaml selbst anheben. Lesen Sie davor die Release Notes, denn Renovate entfernt bei Major-Versionen gelegentlich Optionen. Der Sprung von 43 auf 44 brachte laut Projekt keine Breaking Changes. Das alte Preset config:base heißt config:recommended, Renovate übersetzt den alten Namen noch automatisch.

Für Image-Updates anderer Container siehe 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 nutzt dann den Standard-Endpunkt (gitea.com bzw. gitlab.com) und scheitert mit 401. Endpunkt wie in Schritt 7 setzen.
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üfen Sie mit docker volume ls | grep renovate. Alternativ: renovate/renovate:44-full verwenden (alle Tools vorinstalliert, ~2,6 GB).
5. config.js nicht gefunden: Mount ./renovate-config:/usr/src/app und Leserechte für User 12021 prüfen (Ordner 755, Datei 644).
6. Keine Aktion, Exit-Code 0, aber keine PRs: Entweder RENOVATE_REPOSITORIES ist leer und RENOVATE_AUTODISCOVER=false, oder alle Dependencies sind bereits aktuell. Endet der Lauf ohne Repository started, fehlt die Repo-Angabe.
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 in der .env setzen.

Häufige Fragen

Wie plane ich Renovate-Läufe ohne Cron?

Mit einem systemd-Timer, der Fehler ins Journal schreibt. Details zeigt die Anleitung systemd-Service selbst erstellen und verwalten.

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

Das Standard-Image (~440 MB) lädt Paketmanager-Tools beim ersten Lauf nach und legt sie im Cache-Volume ab. Das Full-Image (44-full, ~2,6 GB) enthält alle Tools und eignet sich für Umgebungen ohne Internetzugang. Für Server mit Internet reicht das Standard-Image.

Wie teste ich Renovate ohne echte PRs?

Setzen Sie dryRun: 'full' in der config.js. Renovate protokolliert dann, welche PRs es anlegen würde, ohne Branches oder PRs zu erstellen (siehe Schritt 5).

Kann ich mehrere Plattformen gleichzeitig betreiben?

Nein – eine Renovate-Instanz bedient genau eine Plattform (RENOVATE_PLATFORM). Für GitHub und Gitea parallel richten Sie 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?

Legen Sie im jeweiligen Repository eine renovate.json im Stammverzeichnis an (z. B. mit "extends": ["config:recommended"]). Sie überschreibt die globalen Einstellungen aus der config.js, etwa für strengere Regeln in kritischen Repos.

Wie verwalte ich die geöffneten Renovate-PRs?

Renovate aktualisiert offene PRs, sobald eine neuere Version erscheint, und schließt überholte PRs selbst. Sie mergen oder lehnen ab.

Fazit

Renovate hält Abhängigkeiten in Ihren Repositories automatisch aktuell. Der Betrieb als Docker-Container ist schlank: keine Datenbank, kein dauerhaft laufender Prozess, nur ein Cron-Job, eine .env und eine config.js. Planen Sie für die Einrichtung etwa 20 Minuten ein. Als Ergänzung finden Sie in der Anleitung Docker-Images auf Schwachstellen scannen mit Trivy ein Werkzeug für die Schwachstellenprüfung 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