Hébergez votre documentation dans un sous-dossier avec Vercel

Suivez ce guide pour héberger votre centre d'aide Ferndesk dans un sous-dossier personnalisé (comme yourdomain.com/help) à l'aide de la fonctionnalité de proxy vers une origine externe de Vercel.

Cette procédure prend environ 10 minutes et nécessite un projet Vercel dans lequel vous pouvez ajouter un fichier de configuration vercel.json.

Vous êtes bloqué ? Contactez [email protected] et nous vous aiderons à terminer votre configuration.

Prérequis

Un espace de travail Ferndesk avec un accès administrateur
Un projet Vercel qui sert votre site web principal
L'accès nécessaire pour ajouter un fichier vercel.json à la racine de votre projet

La configuration d'un sous-dossier personnalisé nécessite qu'un mode de paiement actif soit enregistré.

Étape 1 : Configurez le sous-dossier dans Ferndesk

Commencez par configurer votre centre d'aide Ferndesk afin qu'il utilise un chemin de sous-dossier personnalisé.

Ouvrir les paramètres du centre d'aide

Connectez-vous à votre espace de travail Ferndesk, développez Centre d'aide dans la barre latérale gauche, puis cliquez sur Personnaliser.

Sélectionner un sous-dossier personnalisé

Cliquez sur Domaine personnalisé.

Sélectionnez l'option Sous-dossier personnalisé.

Saisir votre domaine et votre sous-dossier

Saisissez votre domaine dans le champ Domaine (par exemple, www.example.com), puis saisissez le chemin du sous-dossier souhaité dans le champ Sous-répertoire (par exemple, /help ou /docs).

Enregistrer et copier l'hôte Ferndesk

Cliquez sur Configurer le sous-dossier. Une fois la configuration terminée, copiez l'hôte proxy Ferndesk (par exemple, acme.hc.ferndesk.com) : vous en aurez besoin pour la configuration Vercel.

Utilisez le nom d'hôte de production exact de Vercel (par exemple, www.example.com), et non le nom d'hôte d'un déploiement de prévisualisation. Si le nom d'hôte change après le premier déploiement, d'anciennes entrées de cache peuvent subsister.

Étape 2 : Ajouter la configuration du routage Vercel

Créez ou mettez à jour vercel.json à la racine de votre projet afin de transmettre les requêtes à Ferndesk par proxy. Cette configuration utilise les routes de Vercel avec des transformations des en-têtes de requête pour envoyer à Ferndesk le chemin de base et les informations d'hôte requis.

Créer ou ouvrir vercel.json

Si vous n'avez pas encore de fichier vercel.json à la racine de votre projet, créez-en un. Si vous en avez déjà un, ouvrez-le pour le modifier.

Ajouter la configuration

Collez la configuration ci-dessous dans votre fichier vercel.json. Remplacez les espaces réservés par vos valeurs réelles :

PUBLIC_HOST — le nom d'hôte de production de Vercel (par exemple, www.example.com)
FERNDESK_HOST — l'hôte Ferndesk que vous avez copié depuis le tableau de bord Ferndesk (par exemple, acme.hc.ferndesk.com)
BASE_PATH — le chemin de votre sous-dossier, avec la barre oblique initiale (par exemple, /help)

{
  "$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?__bp=__BASE_PATH__",
      "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?__bp=__BASE_PATH__",
      "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?__bp=__BASE_PATH__",
      "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?__bp=__BASE_PATH__",
      "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__/?__bp=__BASE_PATH__",
      "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?__bp=__BASE_PATH__",
      "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__" }
      ]
    }
  ]
}

Le paramètre __bp permet à Ferndesk de servir vos pages d'aide depuis son cache périphérique, afin qu'elles se chargent en bien moins d'une seconde partout dans le monde.

Déployer votre projet

Validez et envoyez vos modifications pour déclencher un nouveau déploiement Vercel. La nouvelle configuration de routage prendra effet une fois le déploiement terminé.

La section headers désactive la mise en cache des réécritures Vercel sur les chemins Ferndesk. Cela empêche la mise en cache d'anciennes réponses Not found lorsque des ressources ou des pages Ferndesk sont demandées avant la configuration complète du proxy.

Étape 3 : Vérifier la configuration

Vérifiez que votre centre d'aide est désormais accessible à l'adresse du chemin de votre sous-dossier personnalisé.

Ouvrir l'URL de votre sous-dossier

Accédez à https://yourdomain.com/help (ou au chemin de sous-dossier de votre choix) dans votre navigateur.

Vérifier le chargement du centre d'aide

Votre centre d'aide Ferndesk devrait s'afficher avec votre image de marque et votre contenu.

Tester la navigation et les ressources

Ouvrez quelques articles pour confirmer que la navigation fonctionne. Vérifiez que les styles, les images et le JavaScript se chargent correctement.

Si votre centre d'aide se charge avec une navigation et des styles fonctionnels, le proxy inverse est correctement configuré. Vos clients peuvent désormais accéder à votre centre d'aide à l'adresse de votre chemin de sous-dossier personnalisé.

Dépannage

Problème	Cause	Solution
Erreur 404 Not Found	Les routes ne sont pas configurées ou le déploiement n'est pas terminé	Vérifiez que `vercel.json` se trouve à la racine de votre projet et que le déploiement est terminé. Vérifiez que tous les espaces réservés ont été remplacés par des valeurs réelles.
Page blanche ou styles incorrects	L'hôte Ferndesk ou le chemin de base est incorrect	Vérifiez que `FERNDESK_HOST` correspond à l'hôte indiqué dans votre tableau de bord Ferndesk et que `BASE_PATH` correspond exactement au sous-dossier configuré.
Les ressources ou le CSS ne se chargent pas après la configuration initiale	Vercel a mis en cache une réponse obsolète	Redéployez votre projet Vercel pour supprimer les réponses mises en cache. La configuration `headers` devrait éviter ce problème pour les prochaines requêtes.
Le centre d'aide fonctionne, mais le nom d'hôte ne correspond pas	L'hôte public indiqué dans les routes est incorrect	Vérifiez que `PUBLIC_HOST` correspond à votre nom d'hôte de production (par exemple, `www.example.com`), et non à une URL de prévisualisation Vercel.

Un problème est survenu ? Contactez-nous à l'adresse [email protected] et nous vous aiderons à terminer votre configuration.

Supprimer le sous-dossier

Pour cesser d'utiliser le sous-dossier personnalisé et revenir à votre URL Ferndesk par défaut :

Supprimer le domaine dans Ferndesk

Dans Ferndesk, accédez à Centre d'aide → Personnaliser → Domaine personnalisé, puis cliquez sur Supprimer le domaine.

Supprimer les routes Vercel

Supprimez ou commentez les entrées headers et routes associées à Ferndesk dans votre fichier vercel.json, puis redéployez.

Étapes suivantes

Cela vous a-t-il été utile ?