Mettre 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 un accès administrateur

• Un domaine dont vous êtes propriétaire (déjà configuré pour utiliser Cloudflare)

• Une connaissance de base du tableau de bord Cloudflare

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

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

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

2. Cliquez sur Domaine personnalisé

3. Sélectionnez l’option Sous-dossier personnalisé

   

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

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

6. Cliquez sur Configurer le sous-répertoire.

É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. Sous BUILD → Compute & AI, accédez à Workers & Pages depuis la barre latérale gauche .

   

3. Cliquez sur Créer une application dans l’angle supérieur droit.

   

4. Sous Commencer avec Hello World!, cliquez sur Commencer.

   

5. Donnez à votre Worker un nom descriptif, comme ferndesk-reverse-proxy, puis cliquez sur Déployer.

   

Étape 3 : Configurer les routes du Worker

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

1. Dans les paramètres du Worker, accédez à l’onglet Paramètres.

   

2. Faites défiler jusqu’à Domaines et routes, puis cliquez sur Ajouter.

   

3. Une fenêtre modale s’ouvre. 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 au chemin de votre sous-dossier. Utilisez *yourdomain.com/help* pour intercepter toutes les requêtes vers le chemin /help et ses sous-chemins.

6. Pour des raisons de sécurité, laissez le Mode d’échec défini sur Échec fermé (bloquer).

7. Cliquez sur Ajouter une route.

   

Étape 3b : Ajouter la route _ferndesk

1. Faites défiler jusqu’à Domaines et routes, puis cliquez sur Ajouter.

   

2. Une fenêtre modale s’ouvre. 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 au chemin de votre sous-dossier. Utilisez *yourdomain.com/_ferndesk* pour intercepter toutes les requêtes vers le chemin /_ferndesk et ses sous-chemins.

5. Pour des raisons de sécurité, laissez le Mode d’échec défini sur Échec fermé (bloquer).

6. Cliquez sur Ajouter une 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 Modifier le code (ou ouvrez 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 autre chemin de sous-dossier (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 commenceront à être servies depuis notre réseau périphérique, avec un temps de chargement généralement inférieur à 100 ms.

3. Cliquez sur Déployer pour publier vos modifications.

   

Étape 5 : Vérifier la configuration

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

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

2. Votre centre d’aide Ferndesk devrait s’afficher avec votre identité visuelle.

3. Testez quelques pages en cliquant sur des liens afin de vérifier que la navigation fonctionne correctement.

Dépannage

Étapes suivantes

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

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