Placez votre documentation dans un sous-dossier avec Cloudflare

Suivez ce guide pour héberger votre centre d’aide Ferndesk dans un sous-dossier personnalisé (comme yourdomain.com/help) en utilisant Cloudflare Workers comme proxy inverse.

Prérequis

• Un espace de travail Ferndesk avec accès administrateur

• Un domaine que vous possédez (déjà pointé vers Cloudflare)

• Une familiarité de base avec le tableau de bord Cloudflare

Étape 1 : configurer le sous-dossier personnalisé dans Ferndesk

Commencez par configurer votre centre d’aide Ferndesk pour utiliser un chemin de sous-dossier personnalisé.

1. Connectez-vous à votre espace de travail Ferndesk, développez Help Center dans la barre latérale gauche, puis cliquez sur Customize.

2. Cliquez sur Custom domain

   

3. Sélectionnez l’option Custom sub-folder

   

4. Saisissez votre domaine dans le champ Domain (par exemple, yourdomain.com).

5. Saisissez le chemin de sous-dossier souhaité dans le champ Subdirectory (par exemple, /help ou /docs).

6. Cliquez sur Configure sub-folder.

Étape 2 : créer un Cloudflare Worker

Créez maintenant un nouveau Cloudflare Worker qui servira de proxy inverse.

1. Connectez-vous à votre tableau de bord Cloudflare.

2. Dans BUILD → Compute & AI, accédez à Workers & Pages depuis la barre latérale gauche .

   

3. Cliquez sur Create application dans le coin supérieur droit.

   

4. Sous Start with Hello World!, cliquez sur Get started.

   

5. Nommez votre Worker de façon descriptive, par exemple ferndesk-reverse-proxy, puis cliquez sur Deploy.

   

Étape 3 : configurer les routes du worker

Configurez la règle de routage qui dirige le trafic depuis votre sous-dossier personnalisé vers le Cloudflare Worker.

1. Dans les paramètres du Worker, allez à l’onglet Settings.

   

2. Faites défiler jusqu’à Domains & Routes puis cliquez sur Add.

   

3. Une fenêtre modale s’ouvrira. Sélectionnez l’option Route.

   

4. Dans la liste déroulante Zone, sélectionnez votre domaine (par exemple, yourdomain.com).

5. Dans le champ Route, saisissez le modèle correspondant à votre chemin de sous-dossier. Utilisez yourdomain.com/help pour intercepter toutes les requêtes vers le chemin /help et ses sous-chemins.

6. Laissez Failure mode réglé sur Fail closed (block) pour des raisons de sécurité.

7. Cliquez sur Add route.

   

Étape 3b : ajout de la route _ferndesk

1. Faites défiler jusqu’à Domains & Routes puis cliquez sur Add.

   

2. Une fenêtre modale s’ouvrira. Sélectionnez l’option Route.

   

3. Dans la liste déroulante Zone, sélectionnez votre domaine (par exemple, yourdomain.com).

4. Dans le champ Route, saisissez le modèle correspondant à votre chemin de sous-dossier. Utilisez yourdomain.com/_ferndesk pour intercepter toutes les requêtes vers le chemin /_ferndesk et ses sous-chemins.

5. Laissez Failure mode réglé sur Fail closed (block) pour des raisons de sécurité.

6. Cliquez sur Add route.

   

Étape 4 : modifier le code du Worker

Mettez maintenant à jour le code du Worker pour gérer la logique du proxy inverse. Le Worker interceptera les requêtes vers votre sous-dossier et les transmettra à Ferndesk.

1. Cliquez sur Edit code (ou accédez à l’éditeur de code depuis le tableau de bord du Worker).

   

2. Remplacez l’intégralité du code worker.js par le script de proxy inverse ci-dessous.

   const HELP_HOST = 'your-company.hc.ferndesk.com'; // your Ferndesk help domain
   const PROXY_PREFIX = '/help'; // the subfolder you chose in Ferndesk
   const PROXY_VERSION = '2';
   
   addEventListener('fetch', (event) => {
   	event.respondWith(handleRequest(event.request));
   });
   
   async function handleRequest(request) {
   	const originalUrl = new URL(request.url);
   
   	// Keep canonical trailing-slash behaviour on the edge
   	if (originalUrl.pathname.endsWith('/') && originalUrl.pathname !== '/') {
   		originalUrl.pathname = originalUrl.pathname.slice(0, -1);
   		return Response.redirect(originalUrl.toString(), 301);
   	}
   
   	// Only intercept the help subtree (and the help assets)
   	if (
   		originalUrl.pathname !== PROXY_PREFIX &&
   		!originalUrl.pathname.startsWith(`${PROXY_PREFIX}/`) &&
   		!originalUrl.pathname.startsWith('/_ferndesk/')
   	) {
   		return fetch(request);
   	}
   
   	// Build the upstream request with the prefix removed
   	const upstreamUrl = new URL(originalUrl.toString());
   	upstreamUrl.hostname = HELP_HOST;
   
   	if (upstreamUrl.pathname === PROXY_PREFIX) {
   		upstreamUrl.pathname = '/';
   	} else if (upstreamUrl.pathname.startsWith(`${PROXY_PREFIX}/`)) {
   		upstreamUrl.pathname = upstreamUrl.pathname.slice(PROXY_PREFIX.length) || '/';
   	}
   
   	// Enables edge caching: tells Ferndesk this render belongs to your
   	// subfolder so it gets its own cache entry.
   	upstreamUrl.searchParams.set('__bp', PROXY_PREFIX);
   
   	const proxyRequest = new Request(upstreamUrl.toString(), request);
   
   	// Let the help app know we are hosted under the subfolder
   	proxyRequest.headers.set('X-Ferndesk-Base-Path', PROXY_PREFIX);
   	proxyRequest.headers.set('X-Forwarded-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Original-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Proxy-Version', PROXY_VERSION);
   
   	// Handle redirects ourselves so renamed articles redirect visitors on
   	// this domain instead of being followed silently.
   	const response = await fetch(proxyRequest, { redirect: 'manual' });
   	if (response.status >= 300 && response.status < 400) {
   		return rewriteRedirect(response, originalUrl);
   	}
   	return response;
   }
   
   // Translates an upstream redirect (on the Ferndesk help host) back onto
   // this site's host and subfolder. External redirects pass through as-is.
   function rewriteRedirect(response, originalUrl) {
   	const location = response.headers.get('location');
   	if (!location) return response;
   
   	const target = new URL(location, `https://${HELP_HOST}`);
   	if (target.hostname !== HELP_HOST) return response;
   
   	target.protocol = 'https:';
   	target.host = originalUrl.host;
   	target.searchParams.delete('__bp');
   
   	const alreadyPrefixed =
   		target.pathname === PROXY_PREFIX || target.pathname.startsWith(`${PROXY_PREFIX}/`);
   	if (!alreadyPrefixed) {
   		target.pathname = target.pathname === '/' ? PROXY_PREFIX : PROXY_PREFIX + target.pathname;
   	}
   
   	// Response headers from fetch are immutable; copy to edit Location.
   	const rewritten = new Response(response.body, response);
   	rewritten.headers.set('location', target.toString());
   	return rewritten;
   }
   Remplacez HELP_HOST par le domaine Ferndesk réel fourni lors de la configuration de votre sous-dossier personnalisé. Remplacez PROXY_PREFIX si vous utilisez un chemin de sous-dossier différent (par exemple, /docs au lieu de /help).

   Vous avez déjà configuré votre sous-dossier il y a quelque temps ? Remplacez simplement le code de votre worker par la version ci-dessus. Tout continuera à fonctionner exactement comme avant, et les pages de votre centre d’aide seront désormais diffusées depuis notre réseau en périphérie, avec un chargement généralement inférieur à 100 ms.

3. Cliquez sur Deploy pour publier vos modifications.

   

Étape 5 : vérifier la configuration

Testez que votre centre d’aide est désormais accessible à l’adresse de votre sous-dossier personnalisé.

1. Ouvrez un nouvel onglet de navigateur et accédez à https://yourdomain.com/help.

2. Vous devriez voir votre centre d’aide Ferndesk chargé avec votre identité visuelle.

3. Testez quelques pages en cliquant sur des liens pour vous assurer que la navigation fonctionne correctement.

Dépannage

Étapes suivantes

• En savoir plus sur la structure des URL du centre d’aide et les chemins sensibles aux sections

• Connecter plutôt un domaine personnalisé (sous-domaine)