Jenkins mit Docker installieren: Open-Source-CI/CD-Server einrichten

Jenkins ist ein Open-Source-Automationsserver für CI/CD: Er baut, testet und verteilt Software, sobald Code in ein Repository kommt oder ein Zeitplan es vorsieht. Die Stärke ist die Erweiterbarkeit über Plugins, die Schwäche der Pflegeaufwand, den genau diese Plugins mit sich bringen. Diese Anleitung richtet Jenkins 2.580.1 LTS mit JDK 21 per Docker Compose auf einem Linux-Server ein, führt durch den Einrichtungsassistenten, legt eine erste Pipeline an und zeigt Sicherung und Wiederherstellung des Datenverzeichnisses. Alle Schritte wurden in einer Testumgebung nachgestellt.

Voraussetzungen

• Linux-Server oder VM mit Docker Engine und Compose-Plugin, siehe Docker und Docker Compose auf Linux installieren. Architektur x86_64 oder arm64.
• 2 CPU-Kerne und 4 GB RAM. Jenkins selbst belegte im Test nach dem ersten Build rund 690 MB bei einer Heap-Grenze von 1 GB; echte Builds im Container brauchen zusätzlich Speicher.
• 10 GB freier Speicher. Das Datenverzeichnis war nach Einrichtung mit den empfohlenen Plugins rund 250 MB groß, Workspaces und Build-Artefakte wachsen mit jedem Projekt.
• Ausgehender Internetzugang für den Plugin-Download aus dem Jenkins-Update-Center.
• Für den Zugriff von anderen Geräten: Subdomain wie jenkins.example.com und ein Reverse Proxy mit HTTPS, siehe Schritt 4.

Eckdaten	Wert
Image	jenkins/jenkins:2.580.1-lts-jdk21 (LTS, OpenJDK 21)
Web-Port	8080 (im Beispiel nur an 127.0.0.1)
Agenten-Port	50000, nur für eingehende Agenten nötig
Daten	/var/jenkins_home als benanntes Volume
Benutzer im Container	jenkins, UID/GID 1000
Datenbank	keine, Jenkins speichert alles als Dateien

Schritt 1: compose.yaml anlegen

Legen Sie einen Projektordner an. Der Ordnername bestimmt das Präfix des Volumes, bei /opt/jenkins heißt es später jenkins_jenkins_home.

sudo mkdir -p /opt/jenkins
cd /opt/jenkins
sudo nano compose.yaml

services:
  jenkins:
    image: jenkins/jenkins:2.580.1-lts-jdk21
    container_name: jenkins
    restart: on-failure
    ports:
      - "127.0.0.1:8080:8080"
      # Nur für eingehende Build-Agenten freigeben:
      # - "50000:50000"
    volumes:
      - jenkins_home:/var/jenkins_home
    environment:
      JENKINS_JAVA_OPTS: "-Xmx1g -Duser.timezone=Europe/Berlin"
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8080/login >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s

volumes:
  jenkins_home:

Zu den Entscheidungen: Der feste Tag 2.580.1-lts-jdk21 verhindert, dass ein pull unbemerkt eine neue Version mit geänderten Plugin-Abhängigkeiten einspielt. Der gleitende Tag lts-jdk21 folgt immer der aktuellen LTS. Für Optionen der Java-VM empfiehlt das offizielle Image JENKINS_JAVA_OPTS statt JAVA_OPTS, weil andere Werkzeuge im Container die allgemeine Variable ebenfalls auswerten. -Xmx1g begrenzt den Heap und passt zu einem Server mit 4 GB RAM; bei größeren Installationen erhöhen Sie den Wert. Das Image bringt curl mit, der Healthcheck funktioniert ohne Zusatzpakete. Den Port 50000 brauchen Sie nur, wenn sich externe Agenten über eine eingehende TCP-Verbindung anmelden; Agenten per SSH benötigen ihn nicht.

Verifizieren: docker compose config -q im Ordner /opt/jenkins endet ohne Ausgabe. Das Image heißt jenkins/jenkins mit Namensraum; das alte Image jenkins ohne Namensraum wird seit Jahren nicht mehr gepflegt.

Schritt 2: Jenkins starten und Einmalpasswort lesen

cd /opt/jenkins
docker compose up -d
docker compose ps
docker compose logs jenkins | grep -E "fully up|initial setup"

Im Test lud Docker das Image in rund 30 Sekunden, nach etwa 15 Sekunden meldete der Container healthy und das Log die Zeile Jenkins is fully up and running. Beim ersten Start erzeugt Jenkins ein zufälliges Einmalpasswort, das den Einrichtungsassistenten schützt:

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Die Ausgabe ist eine 32-stellige Zeichenfolge aus Hexadezimalziffern. Dasselbe Passwort steht auch im Log nach der Zeile Please use the following password to proceed to installation.

ss -tlnp | grep -E ':(8080|50000) '
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/

Verifizieren: docker compose ps zeigt Up … (healthy) und 127.0.0.1:8080->8080/tcp. ss zeigt nur 127.0.0.1:8080 und keinen veröffentlichten Port 50000. Der curl-Aufruf liefert 403: Jenkins verlangt bereits vor dem Assistenten eine Anmeldung, die Weboberfläche läuft also.

Schritt 3: Einrichtungsassistent abschließen

Ohne Reverse Proxy öffnen Sie einen SSH-Tunnel von Ihrem Arbeitsrechner aus und rufen dann http://localhost:8080 im Browser auf:

ssh -L 8080:127.0.0.1:8080 benutzer@server

Der Assistent zeigt die Oberfläche in der Sprache des Browsers, einige Schaltflächen bleiben englisch.

1. Jenkins entsperren: Einmalpasswort aus Schritt 2 einfügen und mit Weiter bestätigen.
2. Plugins: Install suggested plugins wählen. Im Test installierte Jenkins damit 92 Plugins, darunter Pipeline, Git, Credentials Binding und Pipeline Graph View; das dauerte einige Minuten.
3. Erstes Administratorkonto: Benutzername, starkes Passwort, Name und E-Mail-Adresse eintragen, dann Save and Continue. Den Link Skip and continue as admin sollten Sie nicht nutzen, dann bleibt nur das Einmalpasswort als Zugang.
4. Instance Configuration: Als Jenkins URL die spätere Adresse eintragen, etwa https://jenkins.example.com/. Jenkins nutzt sie für Links in Benachrichtigungen und für die Variable BUILD_URL. Mit Save and Finish und Start using Jenkins abschließen.

Verifizieren: Nach dem Assistenten erscheint das Dashboard mit der Meldung „Willkommen bei Jenkins!“, oben rechts steht Ihr Kontoname. Ein Aufruf einer Jenkins-Seite ohne Anmeldung, etwa per curl, liefert weiterhin 403.

Schritt 4: HTTPS über einen Reverse Proxy

Jenkins spricht im Container nur HTTP. Für den Zugriff aus dem Netz stellen Sie einen Reverse Proxy davor, der das Zertifikat verwaltet und an 127.0.0.1:8080 weiterleitet. Die Jenkins-Dokumentation verlangt, dass der Proxy die Kopfzeilen Host, X-Forwarded-Proto und X-Forwarded-Port korrekt setzt. Caddy macht das von sich aus:

jenkins.example.com {
    reverse_proxy 127.0.0.1:8080
}

Mit Traefik oder Nginx gilt dasselbe Prinzip, siehe Traefik als Docker-Reverse-Proxy mit automatischem HTTPS. Soll Jenkins unter einem Unterpfad wie /jenkins laufen, ergänzen Sie in der compose.yaml die Variable JENKINS_OPTS: "--prefix=/jenkins" und leiten den Pfad im Proxy unverändert weiter. Die Jenkins URL unter Jenkins verwalten > System muss zur öffentlichen Adresse passen.

Verifizieren: curl -I https://jenkins.example.com/login liefert Status 200 mit gültigem Zertifikat. Unter Jenkins verwalten erscheint keine Warnung „It appears that your reverse proxy set up is broken“.

Schritt 5: Erste Pipeline anlegen

Eine Pipeline beschreibt den Ablauf als Code. Legen Sie im Dashboard über Element anlegen ein Element vom Typ Pipeline mit dem Namen test-pipeline an und tragen Sie im Abschnitt Pipeline dieses Skript ein:

pipeline {
    agent any
    stages {
        stage('Hallo') {
            steps {
                echo 'Jenkins läuft korrekt'
                sh 'java -version'
            }
        }
    }
}

Speichern Sie und starten Sie den Lauf mit Jetzt bauen. agent any führt den Build hier direkt auf dem Jenkins-Controller aus. Für einen ersten Test ist das in Ordnung; für produktive Builds empfiehlt die Jenkins-Dokumentation getrennte Agenten, damit Build-Skripte keinen Zugriff auf das Datenverzeichnis des Controllers haben. Die Zahl der Ausführer auf dem Controller setzen Sie dann unter Jenkins verwalten > Nodes auf 0.

Verifizieren: Der Build erhält einen grünen Haken. Unter Console Output stehen die Zeile Jenkins läuft korrekt, die Java-Version (im Test OpenJDK 21.0.12.1) und am Ende Finished: SUCCESS.

Schritt 6: Sichern und Wiederherstellen

Konfiguration, Jobs, Build-Verlauf, Plugins und Zugangsdaten liegen in /var/jenkins_home. Die Datei secrets/master.key entschlüsselt die gespeicherten Zugangsdaten; ohne sie sind gesicherte Credentials wertlos. Sichern Sie deshalb immer das ganze Verzeichnis und lagern Sie das Archiv so geschützt wie ein Passwort. Den Volumenamen prüfen Sie mit docker volume ls:

cd /opt/jenkins
sudo mkdir -p /opt/backups
docker compose stop jenkins
docker run --rm -v jenkins_jenkins_home:/data:ro -v /opt/backups:/backup alpine:3.22 \
  tar czf /backup/jenkins_home_$(date +%F).tar.gz -C /data .
docker compose start jenkins

Im Test war das Archiv der frisch eingerichteten Instanz rund 190 MB groß und nach 15 Sekunden fertig. Den größten Teil machen die Plugins aus. Wiederherstellen heißt: Container stoppen, Volume leeren, Archiv zurückspielen.

cd /opt/jenkins
docker compose down
docker run --rm -v jenkins_jenkins_home:/data -v /opt/backups:/backup alpine:3.22 \
  sh -c 'rm -rf /data/* /data/.[!.]* /data/..?*; tar xzf /backup/jenkins_home_2026-10-14.tar.gz -C /data'
docker compose up -d

Im Test wurde der Job test-pipeline nach der Sicherung gelöscht (Jobseite danach 404) und mit dem Archiv zurückgeholt. Nach dem Neustart war der Job samt erfolgreichem Build Nummer 1 wieder da, die Dateien gehörten weiter UID 1000. Für Sicherungen außer Haus mit Rotation siehe 3-2-1-Backup-Strategie umsetzen.

Verifizieren: tar -tzf auf das Archiv listet unter anderem ./config.xml, ./secrets/master.key und ./jobs/test-pipeline/config.xml. Nach einer Probe-Wiederherstellung zeigt docker compose ps wieder (healthy), und Ihre Jobs sind im Dashboard sichtbar.

Schritt 7: Updates einspielen

Jenkins und die Plugins werden getrennt aktualisiert. Die Kernversion wechseln Sie über den Image-Tag, die Plugins über die Oberfläche.

1. Den LTS-Upgrade-Guide für alle übersprungenen Versionen lesen.
2. Sicherung wie in Schritt 6 anlegen.
3. Den Tag in der compose.yaml ändern, etwa auf die nächste LTS mit Endung -lts-jdk21.
4. Container neu erstellen, danach unter Jenkins verwalten > Plugins verfügbare Updates einspielen und Jenkins neu starten.

cd /opt/jenkins
docker compose pull
docker compose up -d
docker image prune -f

Verifizieren: docker inspect jenkins --format '{{.Config.Image}}' zeigt den neuen Tag, docker compose ps meldet (healthy), und die Fußzeile der Oberfläche nennt die neue Versionsnummer.

Typische Fehler

• Container beendet sich mit java.lang.OutOfMemoryError: Der Heap ist zu klein oder der Server hat zu wenig RAM. -Xmx in JENKINS_JAVA_OPTS anpassen und mindestens 1 GB frei halten.
• Permission denied auf /var/jenkins_home: Tritt bei Bind-Mounts auf, weil Jenkins als UID 1000 läuft. Ordner vorher mit sudo chown 1000:1000 vorbereiten oder beim benannten Volume bleiben, wie es das offizielle Image empfiehlt.
• Einmalpasswort fehlt: Jenkins ist noch nicht fertig gestartet. Auf Jenkins is fully up and running im Log warten.
• Plugin-Installation im Assistenten scheitert: Kein ausgehender Zugang zum Update-Center. Bei einem Firmenproxy ergänzen Sie -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=3128 in JENKINS_JAVA_OPTS.
• Warnung zum Reverse Proxy oder falsche Links: Proxy reicht X-Forwarded-Proto oder Host nicht durch, oder die Jenkins URL stimmt nicht. Beides prüfen, siehe Schritt 4.
• Alles weg nach docker compose down -v: Die Option -v löscht auch das Volume mit allen Jobs. Nur mit aktueller Sicherung verwenden.

Häufige Fragen

Braucht Jenkins eine Datenbank?

Nein. Jenkins speichert Konfiguration, Jobs und Build-Verlauf als Dateien in /var/jenkins_home. Deshalb genügt die Sicherung dieses Verzeichnisses.

Kann ich Plugins ohne Assistenten vorinstallieren?

Ja, über ein eigenes Image. Das offizielle Image enthält dafür jenkins-plugin-cli, etwa RUN jenkins-plugin-cli --plugins pipeline-model-definition github-branch-source in einem Dockerfile mit FROM jenkins/jenkins:2.580.1-lts-jdk21. So entsteht eine reproduzierbare Installation.

Wie binde ich Build-Agenten an?

Unter Jenkins verwalten > Nodes legen Sie einen neuen Knoten an. Agenten per SSH brauchen nur SSH-Zugang zum Agenten-Host. Melden sich Agenten selbst an, geben Sie Port 50000 in der compose.yaml frei und erlauben ihn in der Firewall nur für die Agenten-Hosts.

Läuft Jenkins auf ARM?

Das LTS-Image gibt es auch für arm64, etwa für ARM-VPS oder einen Raspberry Pi 5 mit 64-Bit-System.

Jenkins oder Woodpecker CI?

Jenkins ist flexibel und für gemischte Umgebungen mit vielen Integrationen geeignet, verlangt aber regelmäßige Pflege der Plugins. Wer nur Container-Builds aus Gitea oder Forgejo braucht, kommt mit Woodpecker CI schlanker aus.

Fazit

Mit Docker Compose steht Jenkins in wenigen Minuten. Für einen dauerhaft sicheren Betrieb zählen vier Punkte: fester Image-Tag, Weboberfläche nur über HTTPS, Builds auf getrennten Agenten statt auf dem Controller und eine regelmäßig geprüfte Sicherung von /var/jenkins_home samt master.key. Planen Sie die Plugin-Updates als festen Wartungstermin ein.

Weiterführende Anleitungen und Quellen

• Docker und Docker Compose auf Linux installieren
• Traefik als Docker-Reverse-Proxy mit automatischem HTTPS
• Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only
• Woodpecker CI mit Docker einrichten
• 3-2-1-Backup-Strategie praktisch umsetzen
• Quellen: Jenkins-Dokumentation: Installation mit Docker, jenkinsci/docker (README des offiziellen Images), jenkins/jenkins auf Docker Hub, LTS-Upgrade-Guide