Skip to main content

Custom Docs Domain

Serve the Kuploy documentation site on your own domain (e.g., docs.mycompany.com) with your platform's branding — colors, logo, site name, and favicon — applied automatically.

Setup​

1. Save your docs hostname​

  1. Go to Admin → Theme
  2. Scroll to Docs Hostname
  3. Enter your domain (e.g., docs.mycompany.com)
  4. Click Save

2. Configure DNS​

Create a CNAME record pointing your docs domain to Vercel:

docs.mycompany.com.  CNAME  cname.vercel-dns.com.
Alternative CNAME target

You can also CNAME to docs.kuploy.app — both resolve to Vercel's edge network. The cname.vercel-dns.com target is recommended as it's decoupled from any specific domain.

3. Wait for provisioning​

After saving the hostname, the following happens automatically:

  1. Your kuploy-cloud instance reports the docs hostname during its regular license sync (~60 seconds)
  2. kuploy.app registers the domain with the docs hosting infrastructure
  3. An SSL certificate is provisioned for your domain
  4. DNS propagation completes (usually seconds to minutes)

No manual Vercel or infrastructure configuration is needed.

How Theming Works​

When a visitor opens docs.mycompany.com, the docs site:

  1. Detects the custom hostname (any hostname other than docs.kuploy.app or localhost)
  2. Resolves the hostname to your kuploy-cloud instance by calling the docs lookup API
  3. Fetches your theme configuration from your kuploy-cloud instance's theme API
  4. Applies your branding to the page — colors, logo, site name, favicon, footer, and any custom CSS

This happens client-side on every page load (with a 5-minute session cache for performance).

What gets themed​

SettingWhere it appears
Platform NameNavbar title, browser tab title
LogoNavbar logo
FaviconBrowser tab icon
Primary Color (light & dark)Links, buttons, sidebar highlights, code block accents
Footer TextFooter copyright line
Custom CSSInjected globally (for advanced customization)

Light and dark mode each have their own color palette. When a visitor toggles dark mode, the docs site automatically switches to your dark mode colors.

Verifying Your Setup​

Test the hostname lookup​

Once your docs hostname has been synced (after saving and waiting ~60 seconds), verify the lookup works:

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

Expected response:

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

This confirms kuploy.app knows which kuploy-cloud instance owns docs.mycompany.com.

Test the theme endpoint​

Verify your kuploy-cloud instance serves its theme:

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

Expected response:

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

You can also get CSS variables directly:

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

Test end-to-end in the browser​

  1. Open https://docs.mycompany.com in your browser
  2. Open DevTools → Network tab
  3. Look for two requests:
    • GET https://kuploy.app/api/docs/lookup?hostname=docs.mycompany.com → should return 200 with your cloudUrl
    • GET {cloudUrl}/api/theme → should return 200 with your theme JSON
  4. The page should display your branding (colors, logo, site name)

Troubleshooting​

Docs show default Kuploy theme (teal colors)​

The theme-loader silently falls back to the default theme if any step fails. Check each step:

  1. Lookup returns 404 — The hostname hasn't been synced yet.

    • Verify the hostname is saved in Admin → Theme → Docs Hostname
    • Wait for the next license sync (~60 seconds), or trigger a manual sync from Admin → Overview
    • Confirm your license is active

  2. Theme endpoint returns 404 — Your kuploy-cloud instance doesn't have the /api/theme endpoint.

    • Ensure your kuploy-cloud instance is updated to the version that includes the theme API

  3. Theme endpoint returns 500 — Server error in your kuploy-cloud instance.

    • Check your kuploy-cloud server logs

  4. Cached stale response — The browser may have cached a previous failed attempt.

    • Open your browser console on the docs site and run: 
      sessionStorage.removeItem('kuploy_docs_theme');
      location.reload();

DNS not resolving​

  • Verify your CNAME record exists: dig docs.mycompany.com CNAME
  • DNS propagation can take up to 48 hours (usually much faster)
  • Ensure the CNAME target is cname.vercel-dns.com. (with trailing dot) or docs.kuploy.app

SSL certificate errors ("Not Secure")​

  • Vercel provisions SSL automatically, but it requires DNS to be resolving first
  • Wait a few minutes after DNS propagation for certificate provisioning
  • If using a CAA record, ensure it allows Let's Encrypt: mycompany.com. CAA 0 issue "letsencrypt.org"

This is a Vercel suggestion and does not block functionality. Your docs site will work correctly with a CNAME record.

Theme changes not reflecting​

  • The theme endpoint is cached for 60 seconds by the CDN and 5 minutes in the browser session
  • After changing theme settings in Admin → Theme, wait up to 5 minutes or clear the browser cache: 
    sessionStorage.removeItem('kuploy_docs_theme');
    location.reload();

Removing a Custom Docs Domain​

  1. Go to Admin → Theme
  2. Clear the Docs Hostname field
  3. Click Save

On the next license sync, the domain will be automatically removed from the docs hosting infrastructure. You can then delete the CNAME record from your DNS.