Aller au contenu principal

Un domaine de documentation à vous

Servez le site de documentation de Kuploy sur votre propre domaine (docs.masociete.com, par exemple), à vos couleurs — logo, nom du site et favicon compris — appliquées automatiquement.

Mise en place​

1. Enregistrer le nom d'hôte de votre documentation​

  1. Allez dans Admin → Theme
  2. Descendez jusqu'à Docs Hostname
  3. Saisissez votre domaine (par exemple docs.masociete.com)
  4. Cliquez sur Save

2. Configurer le DNS​

Créez un enregistrement CNAME qui fait pointer votre domaine de documentation vers Vercel :

docs.masociete.com.  CNAME  cname.vercel-dns.com.
Autre cible de CNAME

Vous pouvez aussi faire un CNAME vers docs.kuploy.app — les deux résolvent vers le réseau de périphérie de Vercel. La cible cname.vercel-dns.com est recommandée, car elle n'est liée à aucun domaine particulier.

3. Attendre la mise en service​

Après l'enregistrement du nom d'hôte, la suite se déroule toute seule :

  1. Votre instance kuploy-cloud rapporte le nom d'hôte de sa documentation à sa prochaine synchronisation de licence — toutes les heures par défaut, ou tout de suite avec Retry Sync, depuis le tableau de bord d'administration
  2. kuploy.app enregistre le domaine auprès de l'infrastructure d'hébergement de la documentation
  3. Un certificat SSL est émis pour votre domaine
  4. La propagation DNS s'achève — en général en quelques secondes à quelques minutes

Aucune configuration manuelle, ni de Vercel ni de l'infrastructure, n'est nécessaire.

Comment fonctionne l'habillage​

Lorsqu'un visiteur ouvre docs.masociete.com, le site de documentation :

  1. détecte le nom d'hôte personnalisé — tout nom d'hôte autre que docs.kuploy.app ou localhost ;
  2. résout ce nom d'hôte vers votre instance kuploy-cloud, en appelant l'API de recherche de la documentation ;
  3. récupère votre configuration de thème depuis l'API de thème de votre instance kuploy-cloud ;
  4. applique vos couleurs à la page — teintes, logo, nom du site, favicon, pied de page, et toute CSS personnalisée.

Cela se produit côté navigateur, à chaque chargement de page, avec une mise en cache de session de cinq minutes pour la performance.

Ce qui est habillé​

RéglageOù cela apparaît
Platform NameLe titre de la barre de navigation, le titre de l'onglet du navigateur
LogoLe logo de la barre de navigation
FaviconL'icône de l'onglet du navigateur
Primary Color (clair et sombre)Les liens, les boutons, les surlignages de la barre latérale, les accents des blocs de code
Footer TextLa ligne de copyright, en pied de page
Custom CSSInjectée globalement, pour les personnalisations avancées

Les modes clair et sombre ont chacun leur palette. Lorsqu'un visiteur bascule en mode sombre, le site de documentation passe automatiquement à vos couleurs sombres.

Ce qui ne l'est pas​

La typographie, le rayon des angles, les bordures et les surfaces neutres font partie du design propre au site de documentation, et non de votre configuration de thème : vos couleurs, votre logo, votre nom, votre favicon et votre pied de page se posent par-dessus.

La CSS personnalisée après la refonte de 2026

Le thème par défaut a été rafraîchi pour s'accorder à kuploy.app : Space Grotesk pour les titres et l'interface, IBM Plex Mono pour le code et les en-têtes de tableaux, des angles droits partout (le rayon de bordure est à 0), et des bordures d'un cheveu en lieu et place des ombres.

Vos couleurs ne sont pas touchées — elles sont appliquées comme variables en ligne, qui prennent le dessus sur la feuille de style : rien de tout cela ne change votre palette. Mais si votre CSS personnalisée avait été écrite pour l'apparence précédente — cartes arrondies, ancienne pile de polices système, ombres portées — elle peut désormais se battre contre les valeurs par défaut. Un coup d'œil à votre domaine de documentation vaut la peine ; le plus souvent, le correctif consiste à supprimer des règles devenues inutiles.

Vérifier votre mise en place​

Tester la résolution du nom d'hôte​

Une fois le nom d'hôte de votre documentation synchronisé, vérifiez que la résolution fonctionne :

curl -s "https://kuploy.app/api/docs/lookup?hostname=docs.masociete.com"

Réponse attendue :

{
  "cloudUrl": "https://console.masociete.com"
}

Cela confirme que kuploy.app sait quelle instance kuploy-cloud possède docs.masociete.com.

Tester le point d'accès du thème​

Vérifiez que votre instance kuploy-cloud sert bien son thème :

curl -s "https://console.masociete.com/api/theme"

Réponse attendue :

{
  "siteName": "MaSociete Cloud",
  "logoUrl": "https://console.masociete.com/uploads/logo.png",
  "faviconUrl": null,
  "colorsLight": { "primary": "220 90% 50%", ... },
  "colorsDark": { "primary": "220 90% 70%", ... },
  "customCss": null,
  ...
}

Vous pouvez aussi obtenir directement les variables CSS :

curl -s "https://console.masociete.com/api/theme?format=css"

Tester de bout en bout, dans le navigateur​

  1. Ouvrez https://docs.masociete.com dans votre navigateur
  2. Ouvrez les outils de développement, onglet Network
  3. Guettez deux requêtes :
    • GET https://kuploy.app/api/docs/lookup?hostname=docs.masociete.com → doit renvoyer 200, avec votre cloudUrl
    • GET {cloudUrl}/api/theme → doit renvoyer 200, avec le JSON de votre thème
  4. La page doit s'afficher à vos couleurs : teintes, logo, nom du site

Dépannage​

La documentation affiche le thème Kuploy par défaut (les teintes sarcelle)​

Le chargeur de thème retombe silencieusement sur le thème par défaut dès qu'une étape échoue. Vérifiez-les une à une :

  1. La résolution renvoie 404 — le nom d'hôte n'a pas encore été synchronisé.

    • Vérifiez qu'il est bien enregistré sous Admin → Theme → Docs Hostname
    • Attendez la prochaine synchronisation de licence, ou cliquez sur Retry Sync depuis le tableau de bord d'administration pour en déclencher une tout de suite
    • Vérifiez que votre licence est active

  2. Le point d'accès du thème renvoie 404 — votre instance kuploy-cloud n'expose pas /api/theme.

    • Assurez-vous qu'elle est à jour, dans une version qui comporte l'API de thème

  3. Le point d'accès du thème renvoie 500 — une erreur serveur dans votre instance kuploy-cloud.

    • Consultez les journaux de votre serveur kuploy-cloud

  4. Une réponse périmée en cache — le navigateur a peut-être mis en cache une tentative précédemment échouée.

    • Ouvrez la console de votre navigateur sur le site de documentation, et exécutez : 
      sessionStorage.removeItem('kuploy_docs_theme');
      location.reload();

Le DNS ne résout pas​

  • Vérifiez que votre enregistrement CNAME existe : dig docs.masociete.com CNAME
  • La propagation DNS peut prendre jusqu'à 48 heures — généralement bien moins
  • Assurez-vous que la cible du CNAME est cname.vercel-dns.com. (avec le point final) ou docs.kuploy.app

Des erreurs de certificat SSL (« Non sécurisé »)​

  • Vercel émet le certificat SSL automatiquement, mais il faut d'abord que le DNS résolve
  • Attendez quelques minutes après la propagation DNS, le temps de l'émission du certificat
  • Si vous utilisez un enregistrement CAA, assurez-vous qu'il autorise Let's Encrypt : masociete.com. CAA 0 issue "letsencrypt.org"

C'est une suggestion de Vercel, qui ne bloque rien. Votre site de documentation fonctionnera correctement avec un enregistrement CNAME.

Les changements de thème n'apparaissent pas​

  • Le point d'accès du thème est mis en cache 60 secondes par le CDN, et cinq minutes dans la session du navigateur
  • Après avoir modifié vos réglages sous Admin → Theme, attendez jusqu'à cinq minutes, ou videz le cache du navigateur : 
    sessionStorage.removeItem('kuploy_docs_theme');
    location.reload();

Retirer un domaine de documentation personnalisé​

  1. Allez dans Admin → Theme
  2. Videz le champ Docs Hostname
  3. Cliquez sur Save

À la synchronisation de licence suivante, le domaine sera automatiquement retiré de l'infrastructure d'hébergement de la documentation. Vous pourrez alors supprimer l'enregistrement CNAME de votre DNS.