Serveur Nginx - Hébergement de sous-dossiers

Pour héberger votre base de connaissances Document360 dans un sous-dossier (comme example.com/docs) via le serveur Nginx, des configurations spécifiques sont requises. Cet article vous guide pour activer les modules nécessaires, configurer les règles de proxy et de réécriture, ainsi que gérer les chemins pour les articles, les API et les sitemaps. Il explique également comment gérer correctement la redirection des URL pour éviter les problèmes de contenu en double dans les moteurs de recherche.

Pour en savoir plus sur Nginx, consultez la documentation de Nginx.

Création d'un sous-dossier ou d'un sous-répertoire

Exemple :

NOTE

Remplacez le domaine d'exemple par votre propre domaine/domaine personnalisé fourni par Document360.

• Exemple de domaine représenté en utilisant example.document360.io

• Chemin de sous-dossier/sous-répertoire (/docs) représenté comme example.document360.io/docs

1. Ajoutez les blocs de localisation suivants dans votre fichier de configuration Nginx (/etc/nginx/default).

location /docs {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

2. Redémarrer le serveur web Nginx

3. Par exemple, si vous utilisez Nginx sous Linux, utilisez la commande
   $ sudo systemctl restart nginx

NOTE

Si vous êtes sur KB Site 2.0 et souhaitez héberger votre base de connaissances en sous-dossier, vous devez définir les deux :

• Le chemin du sous-dossier (par exemple, /docs, /help)

• Le chemin de l'API du site (par exemple, /api, /docs-api)

Après avoir défini ces valeurs, vous devez également configurer les blocs correspondants location dans votre serveur web pour proxy à la fois le trafic UI et API. Vous pouvez trouver l'exemple de configuration de l'API dans la section ci-dessous.

Utilisation d'un chemin de sous-dossier/sous-répertoire personnalisé

• Vous pouvez configurer votre base de connaissances sur des chemins de sous-répertoire autres que /docs.
  Par exemple, /help, /support, etc.

• Lors de la configuration d'autres chemins, ajoutez les langages associés à chaque espace de travail.

• Ajoutez quelques lignes supplémentaires pour y parvenir. Redémarrez le serveur une fois terminé.

Exemple :

NOTE

Remplacez le domaine fourni par Document360 et le domaine du sous-répertoire par vos propres domaines. Remplacez aussi le nom de l'espace de travail, le chemin du sous-dossier et la langue par vos exigences.

• Document360 fournit le domaine représenté comme example.document360.io

• Nom de l'espace de travail représenté comme /v1/

• Chemin du sous-dossier représenté comme /help/

• La langue représentée comme /he étant l'hébreu.

location /help {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}

Suppression du slug de l'espace de travail des liens internes

Si nécessaire, vous pouvez retirer les slugs de l'espace de travail des liens internes au niveau proxy inverse NGINX en utilisant sub_filter des règles.

Exemple :

sub_filter "/Version_slug/docs/" "/help/";

Utilisez cette approche uniquement si la structure de votre site nécessite des URL indépendantes de l'espace de travail.

Pourquoi proxy_set_header Accept-Encoding "" est nécessaire

Lorsqu'on héberge une base de connaissances Document360 dans un sous-dossier personnalisé (par exemple, /help), NGINX utilise sub_filter couramment la réécriture d'URLs internes telles que /docs vers /help.

Par défaut, le serveur en amont (Document360) peut renvoyer du HTML compressé en gzip. NGINX ne peut pas appliquer sub_filter de règles sur les réponses compressées.

Cela conduit aux problèmes suivants :

• Les liens internes ne sont pas réécrits

• Les widgets de la page d'accueil continuent de pointer vers /docs

• Rupture des cartes de catégorie et des itinéraires de navigation

Pour garantir que la réécriture de l'URL fonctionne correctement, vous devez désactiver la compression du serveur en amont en ajoutant la directive suivante :

proxy_set_header Accept-Encoding "";

Ce cadre :

Ce réglage est nécessaire chaque fois sub_filter qu'il est utilisé.

Configuration obligatoire du chemin API pour KB Site 2.0

Si vous êtes sur KB Site 2.0, vous devez définir un chemin API personnalisé du site et ajouter un bloc correspondant location dans votre configuration NGINX.

Cela garantit que les requêtes API sont correctement acheminées vers Document360 et évite des problèmes tels que les boucles de redirection ou les appels API défaillants.

Voici un exemple utilisant /api comme chemin de l'API du site :

location /api {
    proxy_pass https://example.document360.io/api;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types *;
    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}

NOTE

Remplacer /api et /docs-api avec les valeurs exactes configurées sous le chemin de l'API Site dans le portail Document360.

Une fois que vous avez ajouté les deux location blocs, redémarrez le serveur web de Nginx. Par exemple, si vous utilisez Nginx sous Linux, utilisez la commande $ sudo systemctl restart nginx.

À utiliser sub_filter_types *; uniquement lors de la réécriture de réponses HTML ou API qui peuvent retourner du contenu non HTML. Évitez de l'utiliser sauf si une réécriture d'URL est nécessaire.

Quand utiliser sub_filter dans le bloc de localisation API

Ajouter sub_filter des règles dans le bloc de localisation de l'API n'est pas toujours nécessaire.

Utilisation sub_filter dans le bloc de localisation API uniquement lorsque :

• Votre chemin d'interface utilisateur est réécrit (par exemple, /docs → /help)

• Les réponses API contiennent des chemins intégrés /docs qui doivent être réécrits

Si votre projet continue d'utiliser /docs le chemin de l'interface utilisateur, n'ajoutez sub_filter pas de règles au bloc API.

IMPORTANT
Si votre domaine est déjà utilisé /api pour une autre application, vous devez mettre à jour le chemin de l'API du site dans le portail Document360 vers une valeur différente (par exemple, /docs-api) et utiliser le même chemin dans votre configuration NGINX.

Le chemin API configuré dans le portail et le bloc de localisation NGINX doivent correspondre exactement.

Pour activer la liste déroulante des espaces de travail

Si vous souhaitez activer la navigation déroulante de votre espace de travail lorsque vous l'hébergez dans un sous-répertoire et un chemin personnalisés, ajoutez le code suivant pour chacun des espaces de travail disponibles dans votre projet.

Exemple :

Supposons que votre projet ait deux espaces de travail, v1 et v2. Dans ce cas, vous devez ajouter deux blocs de code, un pour chaque espace de travail.

NOTE

Remplacez le domaine fourni par Document360 et le domaine du sous-répertoire par vos propres domaines. Remplacez aussi le nom de l'espace de travail, le chemin du sous-dossier et la langue par vos exigences.

• Document360 fournit le domaine représenté comme example.document360.io

• Le nom de l'espace de travail est représenté par /v1/,/v2/

• Chemin du sous-dossier représenté comme /help/

• La langue représentée comme /he étant l'hébreu.

location /v2/help {
    proxy_pass https://example.document360.io/v2/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v2/docs/" "v2/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location /v1/help {
    proxy_pass https://example.document360.io/v1/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location = /v2/docs {
    return 301 /v2/help;
}
-----------------------------------------------------
location = /v1/docs {
    return 301 /v1/help;
}

NOTE

Si vous souhaitez que vos lecteurs naviguent entre les différents espaces de travail publics de votre projet via le menu déroulant (en cliquant de la souris), ajoutez le bloc de localisation pour tous les espaces de travail disponibles.

1. Redémarrer le serveur web Nginx

2. Par exemple, si vous utilisez Nginx sous Linux, utilisez la commande
   $ sudo systemctl restart nginx

Liens utiles

Voici quelques liens externes qui pourraient vous aider à comprendre en détail les blocs de localisation des serveurs Nginx :

• NGINX Docs : Configuration de NGINX et NGINX Plus en tant que serveur Web

• DigitalOcean : Comprendre les algorithmes de sélection des serveurs et de blocs de localisation Nginx

Génération de carte de site

Exemple :

NOTE

Remplacez le domaine d'exemple par votre propre domaine/domaine personnalisé fourni par Document360.

• Exemple de domaine représenté en utilisant example.document360.io

• Le préfixe sitemap reste le même sauf pour le code de la langue (en, fr, de, etc.)  example.document360.io/sitemap.xml.en

location /sitemap.xml.en {
    proxy_pass https://example.document360.io/sitemap.xml.en;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types text/xml;
    sub_filter "https://www.example.document360.io/docs/" "https://www.example.document360.io/help/";
    sub_filter_once off;
 }

Page d'accueil hébergée dans un sous-dossier

Pour héberger la page d'accueil de votre projet sur un chemin personnalisé de sous-répertoire ou de sous-dossiers, ajoutez le code suivant pour chacun des espaces de travail de la page d'accueil disponibles dans votre projet.

Exemple :

Supposons que votre projet ait deux espaces de travail, V1 et V2. Dans ce cas, vous devez ajouter deux blocs de code, un pour chaque espace de travail.

NOTE

Remplacez le domaine fourni par Document360 et le domaine du sous-répertoire par vos propres domaines. Remplacez aussi le nom de l'espace de travail, le chemin du sous-dossier et la langue par vos exigences.

• Document360 fournit le domaine représenté comme example.document360.io

• Le nom de l'espace de travail est représenté par /v1/,/v2/

location =/v1 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location =/v2 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location /v1/en {
  return 301 /v1;
}

location /v2/en {
  return 301 /v2;
}

ASTUCE PRO

Le signe égal peut être utilisé si la localisation doit correspondre exactement à l'URI de la requête. Lorsque ce modificateur est associé, la recherche s'arrête ici. Pour plus d'informations, cliquez ici.

Exemple : location =/help {

2. Redémarrer le serveur web Nginx

3. Par exemple, si vous utilisez Nginx sous Linux, utilisez la commande
   $ sudo systemctl restart nginx

Page d'accueil du site de la base de connaissances

Que se passe-t-il ensuite ?

Une fois que vous avez configuré avec succès le serveur web, votre site de base de connaissances est en ligne sur votre sous-dossier/sous-répertoire personnalisé. Cependant, l'URL existante de votre projet servira les requêtes.

Par exemple, example.document360.io et example.com/docs (si /docs c'est le chemin de votre dossier) pointera vers le site de la base de connaissances.

Cela peut entraîner des doublons de contenu dans les moteurs de recherche (Google, Bing, etc.). Pour éviter cela, une redirection du sous-domaine du projet Document360 vers votre domaine personnalisé sera nécessaire.

NOTE

Pour permettre la redirection de example.document360.io vers example.com/docs, veuillez nous contacter à support@document360.com.

URL canonique pour l'hébergement de sous-dossiers

Lorsque vous hébergez votre base de connaissances dans un sous-dossier, vous devez configurer une URL canonique pour garantir que les moteurs de recherche indexent votre domaine personnalisé et le chemin du sous-dossier, et non le domaine par défaut *.document360.io .

Cela évite l'indexation en double et améliore les performances SEO.

Comment définir l'URL canonique

1. Va dans Paramètres > site de la base de connaissances > Hébergement de sous-dossiers > domaine personnalisé.

2. Entrez l'URL complète du sous-dossier (par exemple, https://example.com/help).

3. Cliquez sur Enregistrer.

Une fois configuré, les moteurs de recherche considéreront l'URL du sous-dossier comme la source principale pour l'indexation.

Dépannage

Cette section fournit des conseils étape par étape pour résoudre les problèmes courants que vous pourriez rencontrer lors du processus d'installation de NGINX. Des problèmes d'hébergement de sous-dossiers aux échecs de tests de configuration, chaque solution est conçue pour vous aider à identifier et résoudre rapidement les obstacles potentiels, garantissant une configuration fluide et efficace du serveur.

Résolution d'une directive de localisation invalide dans NGINX

Erreur : nginx : [urgence] la directive « localisation » n'est pas autorisée ici

Cette erreur survient lorsqu'une directive de localisation est placée en dehors de son contexte valide, par exemple en dehors du bloc serveur. Dans NGINX, les blocs de localisation doivent être définis au sein d'un bloc serveur.

Étapes à résoudre :

1. Assurez-vous que le bloc de localisation est placé correctement dans le bloc serveur. Voir le bloc d'exemple ci-dessous :

   server {
       listen 80;
       server_name example.com;
       location /docs {
           proxy_pass https://example.document360.io/docs;
           proxy_set_header Host example.document360.io;
       }
   }

2. Pour éviter ce problème, ne placez pas les directives de localisation dans le contexte global http ou en dehors de celui-ci server .

3. Si le problème persiste après avoir suivi ces étapes, veuillez contacter l’équipe d’assistance Document360 pour obtenir de l’aide supplémentaire : Contacter l’assistance Document360

Problème de disponibilité du package Certbot

Erreur : Aucun package Certbot disponible

Ce problème survient souvent lorsque le dépôt EPEL (requis pour l'installation de Certbot sur les distributions basées sur RHEL) n'est pas activé, ou que le gestionnaire de paquets ne parvient pas à localiser Certbot sur les distributions basées sur RHEL.

Étapes à résoudre :

1. Activez le dépôt EPEL en utilisant le code ci-dessous :

   sudo yum install epel-release

2. Mettez à jour le cache du dépôt et essayez de réinstaller Certbot en utilisant le code ci-dessous :

   sudo yum install certbot

3. Assurez-vous que votre instance a accès à Internet pour récupérer les fichiers du dépôt. Si le problème persiste, vérifiez les fichiers de configuration du dépôt dans /etc/yum.repos.d/.

4. Si le problème persiste après avoir suivi ces étapes, veuillez contacter l’équipe d’assistance Document360 pour obtenir de l’aide supplémentaire : Contacter l’assistance Document360

Problème de test de configuration NGINX

Erreur : Test de configuration NGINX échoué

Ce problème survient lorsqu'une erreur de syntaxe apparaît dans le fichier de configuration NGINX.

Étapes pour résoudrepar exemple :

1. Exécutez la commande de test de configuration :

   sudo nginx -t

2. Examinez le message d'erreur et le numéro de ligne, comme dans l'exemple ci-dessous :

   nginx: [emerg] invalid parameter "proxy_pas" in /etc/nginx/sites-enabled/example:22
   nginx: configuration file /etc/nginx/nginx.conf test failed

3. Ouvrez le fichier /etc/nginx/sites-enabled/example spécifié et corrigez le problème de configuration. Par exemple :

   # Incorrect
   proxy_pas https://example.com;
   
   # Correct
   proxy_pass https://example.com;

4. Une fois le problème de configuration corrigé, redémarrez NGINX :

   sudo systemctl restart nginx

5. Si le problème persiste après avoir suivi ces étapes, veuillez contacter l’équipe d’assistance Document360 pour obtenir de l’aide supplémentaire : Contacter l’assistance Document360

Émission de certificat SSL

Erreur : Le certificat SSL ne fonctionne pas

Ce problème peut survenir à cause d'une configuration SSL NGINX incorrecte ou lorsqu'il y a un souci avec le certificat installé. Les détails du certificat, tels que le domaine et la date d'expiration, peuvent ne pas correspondre aux détails de configuration.

Étapes à résoudre :

1. Vérifiez les fichiers de certificats en utilisant le code ci-dessous :

   openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -text -noout

2. Assurez-vous que votre configuration correspond aux détails du certificat, tels que le domaine et la date d'expiration.

3. Assurez-vous que la configuration SSL de NGINX est correcte. Référez-vous au code ci-dessous comme exemple :

   server {
       listen 443 ssl;
       server_name yourdomain.com;
       
       ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
   }

4. Une fois terminé, redémarrez NGINX en utilisant le code ci-dessous :

   sudo systemctl restart nginx

5. Si le problème persiste après avoir suivi ces étapes, veuillez contacter l’équipe d’assistance Document360 pour obtenir de l’aide supplémentaire : Contacter l’assistance Document360

proxy_set_header Accept-Encoding "";