Placez 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 du proxy d'origine externe de Vercel.

Cette opération 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 : configurer 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 Chemin (par exemple, /help ou /docs).

Enregistrer et copier l'hôte Ferndesk

Cliquez sur Configurer le sous-répertoire. 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 votre nom d'hôte de production Vercel exact (par exemple, www.example.com), et non le nom d'hôte d'un déploiement d'aperçu. Si le nom d'hôte change après le premier déploiement, des entrées de cache obsolètes peuvent subsister.

Étape 2 : ajouter la configuration du routage Vercel

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

Créer ou ouvrir vercel.json

Si votre projet ne contient pas encore de fichier vercel.json à sa racine, créez-en un. Si ce fichier existe déjà, 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 — votre nom d'hôte de production 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__/_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 en périphérie, 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 du 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 de réponses obsolètes 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 que le centre d'aide se charge

Vous devriez voir votre centre d'aide Ferndesk avec votre image de marque et votre contenu.

Tester la navigation et les ressources

Ouvrez quelques articles pour vérifier 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 via le chemin de votre 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 vierge 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 effacer les réponses mises en cache. La configuration `headers` devrait empêcher 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 utilisé 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 d'aperçu 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 sous-répertoire.

Supprimer les routes Vercel

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

Étapes suivantes

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