Dokumentation in einem Unterordner mit Vercel hosten

Folgen Sie dieser Anleitung, um Ihr Ferndesk Help Center in einem benutzerdefinierten Unterordner (wie ihredomain.de/hilfe) unter Verwendung des External-Origin-Proxyings von Vercel zu hosten.

Dies dauert etwa 10 Minuten und erfordert ein Vercel-Projekt, in dem Sie eine Konfigurationsdatei vercel.json hinzufügen können.

Kommen Sie nicht weiter? Kontaktieren Sie [email protected] und wir helfen Ihnen, Ihre Einrichtung abzuschließen.

Voraussetzungen

Ein Ferndesk-Workspace mit Administratorzugriff
Ein Vercel-Projekt, das Ihre Hauptwebsite bereitstellt
Zugriff zum Hinzufügen einer vercel.json-Datei im Stammverzeichnis Ihres Projekts

Schritt 1: Konfigurieren Sie den Unterordner in Ferndesk

Konfigurieren Sie zunächst Ihr Ferndesk Help Center so, dass es einen benutzerdefinierten Unterordnerpfad verwendet.

Open Help Center settings

Melden Sie sich in Ihrem Ferndesk-Workspace an, erweitern Sie Help Center in der linken Seitenleiste und klicken Sie dann auf Anpassen (Customize).

Select Custom sub-folder

Klicken Sie auf Benutzerdefinierte Domain (Custom domain).

Wählen Sie die Option Benutzerdefinierter Unterordner (Custom sub-folder).

Enter your domain and subfolder

Geben Sie Ihre Domain im Feld Domain ein (z. B. www.beispiel.de) und geben Sie dann Ihren gewünschten Unterordnerpfad im Feld Unterverzeichnis (Subdirectory) ein (z. B. /hilfe oder /docs).

Save and copy the Ferndesk host

Klicken Sie auf Unterordner konfigurieren (Configure sub-folder). Kopieren Sie nach der Konfiguration den Ferndesk-Proxy-Host (z. B. acme.hc.ferndesk.com) – Sie benötigen diesen für die Vercel-Konfiguration.

Verwenden Sie Ihren exakten Vercel-Produktions-Hostnamen (z. B. www.beispiel.de), nicht den Hostnamen eines Preview-Deployments. Wenn sich der Hostname nach dem ersten Deployment ändert, können veraltete Cache-Einträge bestehen bleiben.

Schritt 2: Vercel-Routing-Konfiguration hinzufügen

Erstellen oder aktualisieren Sie die Datei vercel.json in Ihrem Projektstammverzeichnis, um Anfragen an Ferndesk weiterzuleiten. Diese Konfiguration verwendet die routes von Vercel mit Request-Header-Transformationen, um Ferndesk den erforderlichen Basispfad und Host-Informationen zu senden.

Create or open vercel.json

Falls Sie noch keine vercel.json-Datei in Ihrem Projektstammverzeichnis haben, erstellen Sie eine. Falls doch, öffnen Sie diese zum Bearbeiten.

Add the configuration

Fügen Sie die untenstehende Konfiguration in Ihre vercel.json-Datei ein. Ersetzen Sie die Platzhalter durch Ihre tatsächlichen Werte:

PUBLIC_HOST — Ihr Vercel-Produktions-Hostname (z. B. www.beispiel.de)
FERNDESK_HOST — der Ferndesk-Host, den Sie aus dem Ferndesk-Dashboard kopiert haben (z. B. acme.hc.ferndesk.com)
BASE_PATH — Ihr Unterordnerpfad einschließlich des führenden Schrägstrichs (z. B. /hilfe)

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "headers": [
    {
      "source": "/_ferndesk",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "/_ferndesk/:match*",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "__BASE_PATH__",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "__BASE_PATH__/:match*",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    }
  ],
  "routes": [
    {
      "src": "/_ferndesk",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "/_ferndesk/(.*)",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/_ferndesk",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/_ferndesk/(.*)",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__",
      "dest": "https://__FERNDESK_HOST__/",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/(.*)",
      "dest": "https://__FERNDESK_HOST__/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    }
  ]
}

Deploy your project

Commiten und pushen Sie Ihre Änderungen, um ein neues Vercel-Deployment auszulösen. Die neue Routing-Konfiguration wird wirksam, sobald das Deployment abgeschlossen ist.

Der Abschnitt headers deaktiviert das Rewrite-Caching von Vercel für Ferndesk-Pfade. Dies verhindert, dass veraltete Not found-Antworten zwischengespeichert werden, wenn Ferndesk-Assets oder -Seiten angefordert werden, bevor der Proxy vollständig konfiguriert ist.

Schritt 3: Überprüfen Sie die Einrichtung

Testen Sie, ob Ihr Help Center nun über Ihren benutzerdefinierten Unterordnerpfad erreichbar ist.

Open your subfolder URL

Rufen Sie https://ihredomain.de/hilfe (oder den von Ihnen gewählten Unterordnerpfad) in Ihrem Browser auf.

Check that the help center loads

Sie sollten Ihr Ferndesk Help Center mit Ihrem Branding und Ihren Inhalten sehen.

Test navigation and assets

Klicken Sie sich durch einige Artikel, um zu bestätigen, dass die Navigation funktioniert. Überprüfen Sie, ob Styling, Bilder und JavaScript korrekt geladen werden.

Wenn Ihr Help Center mit funktionierender Navigation und Styling geladen wird, ist der Reverse Proxy korrekt konfiguriert. Ihre Kunden können nun über Ihren benutzerdefinierten Unterordnerpfad auf Ihr Help Center zugreifen.

Fehlerbehebung

Problem	Ursache	Lösung
Fehler 404 Not Found	Routen nicht konfiguriert oder Deployment nicht abgeschlossen	Überprüfen Sie, ob sich `vercel.json` in Ihrem Projektstammverzeichnis befindet und das Deployment abgeschlossen ist. Prüfen Sie, ob alle Platzhalter durch tatsächliche Werte ersetzt wurden.
Leere Seite oder fehlerhaftes Styling	Ferndesk-Host oder Basispfad ist falsch	Überprüfen Sie noch einmal, ob `FERNDESK_HOST` mit dem Host aus Ihrem Ferndesk-Dashboard übereinstimmt und ob `BASE_PATH` exakt Ihrem konfigurierten Unterordner entspricht.
Assets oder CSS werden nach der Ersteinrichtung nicht geladen	Vercel hat eine veraltete Antwort zwischengespeichert	Führen Sie ein Redeployment Ihres Vercel-Projekts durch, um zwischengespeicherte Antworten zu löschen. Die `headers`-Konfiguration sollte dies für zukünftige Anfragen verhindern.
Help Center funktioniert, aber der Hostname stimmt nicht überein	Falscher öffentlicher Host in den Routen	Stellen Sie sicher, dass `PUBLIC_HOST` Ihr Produktions-Hostname ist (z. B. `www.beispiel.de`), keine Vercel-Preview-URL.

Etwas ist schiefgelaufen? Kontaktieren Sie uns unter [email protected] und wir helfen Ihnen, Ihre Einrichtung abzuschließen.

Den Unterordner entfernen

Um die Verwendung des benutzerdefinierten Unterordners zu beenden und zu Ihrer standardmäßigen Ferndesk-URL zurückzukehren:

Remove the domain in Ferndesk

Gehen Sie in Ferndesk zu Help Center → Anpassen → Benutzerdefinierte Domain und klicken Sie auf Domain entfernen (Remove Domain).

Remove the Vercel routes

Löschen oder kommentieren Sie die Ferndesk-bezogenen headers- und routes-Einträge in Ihrer vercel.json-Datei aus und führen Sie dann ein Redeployment durch.

Nächste Schritte

War das hilfreich?