Jenkins unter macOS konfigurieren + Xcode-Support

In diesem Tutorial sehen wir uns an, wie Sie einen Jenkins-Server unter macOS einrichten. Inklusive HTTPS-Unterstützung mit Let's Encrypt sowie die Installation des Xcode-Plugins, um Ihnen den Einstieg in die Automatisierung der iOS- und macOS-App-Entwicklung zu erleichtern.

Für diese Installation werden wir einen gehosteten Mac-Server von OakHost verwenden, da dieser über eine öffentliche, statische IP-Adresse verfügt (die für die HTTPS-Unterstützung erforderlich ist) sowie über eine einfache Firewall über ein Web-Interface.

Alle hier durchgeführten Schritte sollten identisch sein, egal ob Sie auf einem Intel-Mac mit macOS Big Sur (oder neuer) oder auf einem Apple Silicon ARM Mac arbeiten.

Jenkins (+Homebrew) installieren#

Jenkins muss mit Homebrew, einem Paketmanager für macOS, installiert werden. Die Installation ist recht einfach:

Öffnen Sie Ihre Terminal-Anwendung oder verbinden Sie per ssh mit Ihrem System.
Gehen Sie in Ihrem Browser zu brew.sh und kopieren Sie den "Install Homebrew"-Code.
Fügen Sie den Code in Ihr Terminal ein und starten Sie die Installation. Sie sollten eine ähnliche Ausgabe wie diese sehen:

Um die Einrichtung abzuschließen, führen Sie diese beiden Zeilen aus, um brew zu Ihrem Pfad hinzuzufügen (ersetzen Sie customer durch Ihren Benutzer):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/customer/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Jetzt geht es an die Installation von Jenkins#

Sobald die Voraussetzungen erfüllt sind, können wir den Jenkins-Server selbst installieren.

Führen Sie in Ihrem Terminal oder über SSH die folgenden Schritte aus, um Jenkins zu installieren und zu starten:

brew install jenkins-lts
brew services start jenkins-lts

Rufen Sie in Ihrem Browser http://localhost:8080 auf, um auf die Jenkins-Einrichtungsseite zuzugreifen. Beachten Sie, dass diese URL nur auf dem Gerät selbst zugänglich ist. Der externe Zugriff funktioniert noch nicht (siehe unten für weitere Details).

Wie der Bildschirm zeigt, verwenden Sie cat /Users/customer/.jenkins/secrets/initialAdminPassword, um das Administrator-Passwort zu erhalten. Ersetzen Sie erneut customer durch Ihren Benutzer.
Kopieren Sie die Ausgabe in die Weboberfläche und klicken Sie auf Continue.
Installieren Sie entweder alle vorgeschlagenen Plugins oder wählen Sie Ihre eigenen Plugins. Natürlich können Sie später weitere Plugins installieren.

Erstellen Sie einen neuen Admin-Benutzer, mit dem Sie sich bei Ihrer neu eingerichteten Jenkins-Instanz anmelden können. Stellen Sie sicher, dass Sie hier ein sicheres Passwort wählen, wenn Sie beabsichtigen, Jenkins öffentlich zugänglich zu machen.
Geben Sie abschließend die Jenkins-URL ein, die Sie für den Zugriff verwenden werden. Sie können sie vorerst so belassen und später in den Einstellungen ändern.
Glückwunsch, Sie sind fertig! Jenkins sollte nun einsatzbereit sein. Lesen Sie weiter, um zu erfahren, wie Sie Ihre Instanz für den externen Zugriff öffnen, HTTPS-Unterstützung mit Let's Encrypt hinzufügen und das Xcode-Plugin installieren können.

Öffentlichen Zugriff konfigurieren#

Dass Jenkins nur auf localhost verfügbar ist, kann ein guter erster Schritt sein, aber im Allgemeinen ist der externe Zugriff über eine Domain oder IP-Adresse erwünscht. Glücklicherweise ist das Ändern der Listening-Adresse und des Ports recht einfach zu bewerkstelligen.

caution

Wenn Sie beabsichtigen, HTTPS auf Ihrer Jenkins-Instanz zu verwenden, überspringen Sie diesen Schritt und fahren Sie mit dem nachfolgenden Abschnitt fort. Hierfür werden wir nginx installieren und ein Reverse-Proxy-Setup konfigurieren. Daher sollte der direkte Jenkins-Zugriff auf localhost beschränkt bleiben.

Um Jenkins auf der öffentlichen Netzwerkschnittstelle lauschen zu lassen und einen anderen Port (z.B. 80) zu wählen, bearbeiten Sie die folgende Datei in einem Editor Ihrer Wahl (ersetzen Sie [Ihre-Version] durch die richtige Jenkins-Version):

/opt/homebrew/Cellar/jenkins-lts/[Ihre-Version]/homebrew.mxcl.jenkins-lts.plist

Wir müssen die beiden Zeilen bezüglich httpListenAddress und httpPort ändern. Für den öffentlichen HTTP-Zugang setzen Sie die Werte 0.0.0.0 und 80:

...
<plist version="1.0">
  <dict>
    ...
    <array>
      ...
      <string>--httpListenAddress=0.0.0.0</string>
      <string>--httpPort=80</string>
    </array>
    ...
  </dict>
</plist>

Um die Änderungen an der Konfigurationsdatei anzuwenden, starten Sie Jenkins neu:

brew services restart jenkins-lts

Überprüfen Sie die Änderungen, indem Sie Jenkins im Browser auf einem externen Gerät öffnen: http://[öffentliche-ip]

HTTPS per nginx Reverse Proxy und Let's Encrypt konfigurieren#

Um Ihre Jenkins-Installation zu sichern, ist es sehr empfehlenswert, die HTTPS-Unterstützung zu aktivieren. Dazu benötigen Sie eine Domain, die auf die öffentliche IP-Adresse Ihres Macs zeigt. Wir werden dann diese Domain verwenden, um HTTPS zu aktivieren und Jenkins dort verfügbar zu machen.

Wenn Sie die plist-Konfiguration im vorherigen Schritt geändert haben, machen Sie die Änderungen rückgängig, um unberechtigten Zugriff von außen zu vermeiden.
Installieren Sie den nginx-Webserver:

brew install nginx

Erstellen Sie eine Konfigurationsdatei namens /opt/homebrew/etc/nginx/servers/jenkins.conf mit folgendem Inhalt:

server {
    listen 80;
    server_name jenkins.meine-domain.beispiel;

    location / {
        proxy_pass          http://localhost:8080;
        proxy_read_timeout  90s;
        proxy_redirect      http://localhost:8080 https://jenkins.meine-domain.beispiel;
        proxy_http_version  1.1;
        proxy_cache_bypass  $http_upgrade;
    
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Port  $server_port;
    }
}

Stellen Sie sicher, dass Sie jenkins.meine-domain.beispiel durch Ihren Domainnamen ersetzen. Wir werden später HTTPS-Unterstützung hinzufügen.

Validieren Sie die neu erstellte Konfiguration, indem Sie sie folgendes ausführen:

nginx -t

Wenn gültig, starten Sie den nginx-Server:

brew services start nginx

Stellen Sie sicher, dass die erforderlichen Ports durch Ihre Firewall zugelassen sind. Wir benötigen 80/tcp für HTTP und 443/tcp für HTTPS, welche geöffnet sein müssen. Bei OakHost können Sie diese einfach über die Firewall-Weboberfläche hinzufügen.

Das SSL/TLS-Zertifikat deployen#

Wenn Sie bereits über ein eigenes SSL/TLS-Zertifikat verfügen, können Sie diesen Schritt getrost überspringen und die nginx-Konfigurationsdatei direkt anpassen. Andernfalls werden wir Let's Encrypt verwenden, um automatisch ein kostenloses Zertifikat auszustellen.

Installieren Sie dazu certbot:

brew install certbot

Fordern Sie dann ein Zertifikat für Ihre konfigurierte nginx-Domain an. Stellen Sie sicher, dass der DNS-Eintrag korrekt auf Ihren Mac zeigt, sonst schlägt die Validierung fehl.

sudo certbot --nginx --nginx-server-root /opt/homebrew/etc/nginx

Geben Sie Ihre E-Mail-Adresse ein, akzeptieren Sie die Bedingungen und wählen Sie anschließend die richtige Domain aus der Auswahl:

Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: jenkins.meine-domain.beispiel
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1
Requesting a certificate for jenkins.meine-domain.beispiel
Performing the following challenges:
http-01 challenge for jenkins.meine-domain.beispiel
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /opt/homebrew/etc/nginx/servers/jenkins.conf
Redirecting all traffic on port 80 to ssl in /opt/homebrew/etc/nginx/servers/jenkins.conf

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled https://jenkins.meine-domain.beispiel
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Sobald dies geschehen ist, hat certbot die nginx-Konfigurationsdatei angepasst, um die neu erhaltenen SSL/TLS-Zertifikate einzubinden. Da certbot als root läuft, sind die Berechtigungen für die Zertifikatsdatei jedoch leider falsch gesetzt. Eine schnelle Lösung ist es, nginx ebenfalls als root zu starten. Daher müssen wir zuerst die aktuell laufende Instanz stoppen und sie dann mit sudo neu starten:

brew services stop nginx
sudo brew services start nginx

Rufen Sie nach Fertigstellung Ihre Domain https://jenkins.meine-domain.beispiel im Browser auf und überprüfen Sie, ob alles funktioniert.
Gehen Sie zu Manage Jenkins -> Configure System und aktualisieren Sie die Jenkins-URL, um auf Ihre neue Domain zu verweisen. Klicken Sie dann auf Save.
Führen Sie abschließend den folgenden Befehl aus, um die automatische Erneuerung des Zertifikats einzurichten:

echo "0 0,12 * * * root python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew -q" | sudo tee -a /etc/crontab > /dev/null

Fertig. Ihre Jenkins-Instanz sollte jetzt sicher über HTTPS zugänglich sein.

Xcode-Unterstützung für Jenkins einrichten#

Wenn Sie beabsichtigen, macOS-, iPadOS- oder iOS-App-Entwicklung mit Jenkins durchzuführen, ist es wahrscheinlich, dass Sie das mitgelieferte Xcode-Integrationsplugin verwenden möchten.

Die Plugin-Installation in Jenkins ist recht einfach:

Navigieren Sie in der Weboberfläche zu Manage Jenkins -> Manage Plugins. Klicken Sie auf den Tab Available und suchen Sie nach xcode.
Wählen Sie das Plugin xCode Integration und klicken Sie auf Download now an install after restart.
Starten Sie den Jenkins-Server nach der Installation einfach über die Befehlszeile neu:

brew services restart jenkins-lts

Fertig!