So fügen Sie einer GitLab Pages-Site ein SSL-Zertifikat und eine benutzerdefinierte Namecheap-Domain hinzu

Foto von Markus Spiske (https://unsplash.com/@markusspiske)

Das Hinzufügen eines SSL-Zertifikats und einer benutzerdefinierten Namecheap-Domain zu einer GitLab Pages-Site kann etwas schwieriger sein, als es scheint.

Wichtige Teile der Setup-Informationen befinden sich in einer manchmal dichten Dokumentation über verschiedene Standorte hinweg. Es kann schwierig sein, festzustellen, ob Sie die Einstellungen korrekt vorgenommen haben, da Sie stundenlang warten müssen, um zu bestätigen, dass Ihre Änderungen übernommen wurden.

Auch wenn Sie wissen, dass etwas nicht stimmt, können Sie nicht immer sagen, was passiert. Dies macht das Debuggen des Problems frustrierend und schwierig zu beheben.

Dieser Leitfaden zielt darauf ab, den Prozess ein wenig einfacher und weniger frustrierend zu gestalten. Es wird davon ausgegangen, dass Sie:

  • Richten Sie Ihr Projekt bereits auf GitLab Pages ein und greifen Sie darauf zu, indem Sie in Ihrem Browser .gitlab.io / eingeben
  • Haben einen benutzerdefinierten Domainnamen zusammen mit einem SSL-Zertifikat über Namecheap gekauft

Schritt 1: Aktivieren Sie das SSL-Zertifikat

Wechseln Sie in Namecheap zur Seite "Produktliste"> "SSL-Zertifikate". Sie sollten eine Liste der SSL-Zertifikate sehen, die Sie gekauft, aber noch nicht aktiviert haben. Klicken Sie im SSL-Zertifikat, das Sie für Ihre Site aktivieren möchten, auf "Aktivieren".

Schritt 2: Generieren Sie die SSL-Zertifikatanforderung

Sie sollten auf eine Seite weitergeleitet worden sein, die wie folgt aussieht:

Um eine CSR zu generieren, müssen Sie den folgenden Befehl in Ihrem Terminal ausführen: openssl req -new -newkey rsa: 2048 -nodes -keyout .key -out .csr.

Als Ergebnis dieses Befehls wird ein privater Schlüssel generiert. VERLIEREN SIE DIESEN SCHLÜSSEL NICHT. Sie werden es später benötigen, wenn Sie Ihr Zertifikat auf GitLab installieren möchten. Sollten Sie es verlieren, müssen Sie eine weitere CSR-Anfrage einreichen.

Wenn Sie möchten, können Sie hier die detaillierten Informationen zum Generieren einer CSR lesen. Die TL; DR lautet jedoch:

  • Es wird dringend empfohlen, dass Sie alle erforderlichen Felder ausfüllen. Ihr CSR könnte während der Aktivierung von Ihnen nicht abgelehnt werden. Wenn Sie diese CSR für eine persönliche Website oder eine Hobby-Website ausfüllen, können Sie für die Felder "Organisation" und "Organisationseinheit" eine NA eingeben.
  • Wenn das Zertifikat für eine bestimmte Unterdomäne ausgestellt wird, müssen Sie die Unterdomäne im Feld "Allgemeiner Name" angeben. Beispiel: subdomain.ssl-zertifikat-host.com
  • Wenn das Zertifikat ein Platzhalterzertifikat sein soll, sollte die Domäne mit einem Sternchen beginnen. Beispiel: * .ssl-certificate-host.com

In diesem Handbuch wird davon ausgegangen, dass Sie das Zertifikat für so etwas wie .com erhalten.

Sobald Sie den Befehl ausgeführt haben, sollten Sie eine CSR- und eine KEY-Datei in Ihrem Arbeitsverzeichnis haben. Öffnen Sie die CSR-Datei, und kopieren Sie den Inhalt darin. Es sollte den Header ----- BEGIN CERTIFICATE REQUEST ----- haben.

Fügen Sie den Inhalt der Datei in das Feld CSR eingeben ein. Die Seite füllt das Domain-Feld auf dem Formular basierend auf den Informationen in der CSR automatisch aus.

Sobald Sie auf "Weiter" klicken, sollte die folgende Seite angezeigt werden:

Überprüfen Sie, ob die Informationen korrekt sind, und klicken Sie erneut auf "Weiter", um zum Schritt "Bestätigen, dass Sie Eigentümer der Domain sind" zu gelangen.

Schritt 3: Bestätigen Sie, dass Sie Eigentümer der Domain sind

Dazu stehen Ihnen verschiedene Optionen zur Verfügung:

  • Email
  • HTTP-basiert
  • DNS-basiert

Ich persönlich hatte Probleme bei der Validierung per E-Mail. Wählen Sie daher für die Zwecke dieses Handbuchs "DNS-basiert" aus. Dazu müssen Sie in den DNS-Einstellungen Ihrer Domain einen CNAME-Wert einrichten, auf den wir später in diesem Handbuch eingehen werden.

Klicken Sie zunächst auf "Weiter", nachdem Sie "DNS-basiert" ausgewählt haben. Wenn Sie diese Form der Validierung jedoch später ändern, können Sie sie ändern.

Schritt 4: Geben Sie an, wer die SSL-Datei erhalten soll

Bestätigen Sie, dass die E-Mail im Feld korrekt ist. Dies ist die E-Mail, die das Zertifikat erhält, sobald es aktiviert wurde.

Schritt 5: Überprüfen und senden

Vergewissern Sie sich, dass die angezeigten Informationen korrekt sind, und klicken Sie dann auf "Senden".

Schritt 6: Richten Sie den CNAME-Eintrag ein, um den Besitz der Domain zu überprüfen

Sobald Sie das Formular abschicken, werden Sie zu einer Seite weitergeleitet, auf der die Details des SSL-Zertifikats mit einem hilfreichen Benachrichtigungsfenster angezeigt werden, das wie folgt aussieht:

Klicken Sie auf den Link für die DNS-basierte DCV-Methode. Sie werden auf eine Seite weitergeleitet, auf der Informationen angezeigt werden, die Sie zuvor eingegeben haben, z.

  • Der Domainname
  • Der Webservertyp, auf dem das Zertifikat installiert wird (sollte Apache, Nginx, cPanel oder ein anderer sein)
  • Verwendete DCV-Methoden

Greifen Sie auf die Dropdown-Optionen für die Schaltfläche "Methoden bearbeiten" rechts neben "Verwendete DCV-Methoden" zu, um auf die Option "Datensatz abrufen" zuzugreifen und darauf zu klicken.

Es erscheint ein Popover mit dem CNAME-Eintrag, den Sie einrichten müssen, um den Besitz der Domain zu bestätigen. Kopieren Sie diese Werte in eine leere Textdatei, da Sie die Seite "Erweitertes DNS" für Ihre Domain aufrufen müssen. Sie können über "Dashboard" oder "Domänenliste"> "Verwalten" (neben Ihrer Domäne in der Liste)> "Erweitertes DNS" darauf zugreifen.

Im Abschnitt "Host-Datensätze":

  • Klicken Sie auf "Neuen Datensatz hinzufügen".
  • Wählen Sie "CNAME Record".
  • Fügen Sie die Werte, die Sie zuvor aus dem Popover "Datensatz abrufen" kopiert haben, in die entsprechenden Felder ein.

Bevor Sie diese Werte jedoch speichern, wird ein bisschen „gotcha“ angezeigt.

Wie Namecheap in seiner Dokumentation ausführt, „fügen sie den Domänennamen automatisch zu den Werten hinzu, die während der Datensatzerstellung übermittelt wurden“. Dies bedeutet, dass der Domain-Name, der im Host-Wert angezeigt wird, ein doppelter Wert ist. Entfernen Sie .com am Ende des "Host" -Werts und Sie können loslegen.

Nachdem Sie diesen Datensatz gespeichert haben, dauert es einige Zeit, bis das Zertifikat ausgestellt wird. Sobald Sie das Zertifikat per E-Mail erhalten haben, fahren Sie mit Schritt 8 fort. Wenn dies noch nicht geschehen ist, richten Sie die zusätzlichen Datensätze ein, die zum Senden von Personen an .gitlab.io / erforderlich sind wenn sie .com eingeben.

Schritt 7: Richten Sie Ihre Host-Einträge in Namecheap ein

Wie in den GitLab-Dokumenten beschrieben, müssen Sie auch nachweisen, dass Sie die benutzerdefinierte Domain besitzen, auf der Sie Ihre GitLab Pages-Site bereitstellen möchten.

Wie bereits erwähnt, wird in diesem Handbuch davon ausgegangen, dass Sie nur example.com (oder www.example.com) verwenden möchten. Daher möchten Sie die folgenden Hostdatensätze hinzufügen:

  • Typ A-Datensatz, Host @, Wert 35.185.44.232 (dies ist die aktuelle GitLab Pages-IP zum Zeitpunkt des Schreibens)
  • Geben Sie CNAME Record, Host www, Value example.com ein (dies stellt sicher, dass Personen, die die Unterdomäne "www" eingeben (d. H. Www.example.com), weiterhin auf Ihre Website zugreifen).
  • Hinweis: Sie können diese erst eingeben, wenn Sie die Domäne über den in Schritt 8 beschriebenen Ablauf "Neue Seitendomäne" hinzugefügt haben. Geben Sie TXT Record, Host @, Wert gitlab-pages-verification-code = 11112222aaaabbbb ein

Schritt 8: Installieren Sie das Zertifikat in GitLab

Wechseln Sie zur Seite "Seiten" Ihres GitLab-Projekts, das Sie einrichten möchten (in der Seitenleiste unter "Einstellungen"> "Seiten").

Um Ihre benutzerdefinierte Domain hinzuzufügen, auf der GitLab Ihre Pages-Site betreut, klicken Sie oben rechts auf die Schaltfläche "Neue Domain". Sie sollten ungefähr Folgendes sehen:

Geben Sie Ihre benutzerdefinierte Domain (example.com) in das Domain-Feld ein und im nächsten Teil wird es interessant.

Wenn Sie nur versuchen, Ihr Zertifikat (example_com.crt) und Ihren privaten Schlüssel (der beim ersten Senden der Zertifikatanforderung generiert wurde) in die Felder einzugeben, wird wahrscheinlich der Fehler "Zertifikat fehlt Zwischenprodukte" angezeigt.

Dies liegt daran, dass GitLab so etwas wie NGINX verwendet, um Anforderungen auf der Pages-IP zu empfangen, bevor die Anforderung an die richtige Site weitergeleitet wird. In der Dokumentation von Namecheap heißt es: "Es ist erforderlich, Ihr Zertifikat mit CA-Zertifikaten in einer einzigen Datei zu kombinieren."

Dies bedeutet für Sie, dass Sie den Text aus den Dateien example_com.crt und example_com.ca im Feld "Zertifikat" kombinieren müssen. Am Ende solltest du etwas haben wie:

Fügen Sie den privaten Schlüssel zum letzten Feld hinzu, und Sie sind fertig. Es wird einige Zeit dauern, bis sich die Änderungen verbreiten. Wenn Sie in ein paar Stunden wieder einchecken, sollte in der URL-Leiste neben Ihrer Adresse ein Hinweis angezeigt werden, dass Ihre Verbindung zu Ihrer Site jetzt sicher ist.

Ressourcen / Referenzen

  • https://about.gitlab.com/features/pages/
  • https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html#dns-txt-record
  • https://www.namecheap.com/support/knowledgebase/article.aspx/9474/69/how-do-i-create-a-pem-file-from-the-certificates-i-received- from-you
  • https://www.namecheap.com/support/knowledgebase/article.aspx/9637/68/how-can-i-complete-the-domain-control-validation-dcv-for-my-SSL-certificate#dns
  • https://stackoverflow.com/a/49124195/2719852