Deploy the Public Site

The public site is a separate Nuxt 3 application with server-side rendering, self-doc-hub-portal. It reads the public API of SelfDocHub and draws the documentation. This page explains how to run it and put it on a domain.

Roles: This is server work, done by whoever runs your SelfDocHub installation. The portal itself has no sign-in and no data of its own.

Requirements#

  • A running SelfDocHub whose license includes publish, reachable from the portal (an internal address is fine).
  • Docker with Docker Compose, or Node.js 20 or newer.
  • A domain name pointing at the portal, with TLS in front of it.

Run it with Docker#

git clone https://github.com/SelfDocHub/self-doc-hub-portal.git
cd self-doc-hub-portal
cp .env.example .env        # set NUXT_DOCS_HUB_URL
docker compose up -d --build

The site is then available on http://localhost:3000. Change the host port with PORTAL_PORT. The container has a health check on /api/health.

Without Compose:

docker build -t self-doc-hub-portal .
docker run -p 3000:3000 -e NUXT_DOCS_HUB_URL=http://hub:8080 self-doc-hub-portal

If SelfDocHub runs on the same host and not in the same Compose network, the default http://host.docker.internal:8080 reaches it through the extra_hosts entry of the compose file.

Settings#

The portal reads these environment variables at start:

Variable Default Purpose
NUXT_DOCS_HUB_URL http://localhost:8080 (Compose: http://host.docker.internal:8080) Address of SelfDocHub as the portal container sees it, without a trailing /.
NUXT_DOMAIN_OVERRIDE empty When set, this domain is always sent to SelfDocHub instead of the Host of the request. Handy for local checks.
NUXT_TRUST_PROXY false true trusts X-Forwarded-Host and X-Forwarded-Proto. Switch it on only behind your own reverse proxy.
NUXT_SITE_ORIGIN empty Public origin used in sitemap.xml, for example https://docs.example.com. Without it the origin is built from the request.
PORTAL_PORT 3000 Port published on the host (Compose only).

How a domain is chosen#

One portal installation serves several domains. For every request the portal takes the domain from the Host header (or from X-Forwarded-Host when NUXT_TRUST_PROXY is on) and sends it to SelfDocHub as X-Public-Domain. SelfDocHub then answers with the site of that domain: its style, languages and published versions.

So the domain you add in Publishing → Domains must be exactly the host readers open, for example docs.example.com. A domain that is not configured answers 404. For a local check, set NUXT_DOMAIN_OVERRIDE to a configured domain: every host is then treated as that domain.

Put it behind Nginx with TLS#

Serve the site over HTTPS and pass the original host on. A minimal Nginx server block:

server {
    listen 443 ssl;
    server_name docs.example.com;

    # ssl_certificate and ssl_certificate_key here

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

With Host passed on, NUXT_TRUST_PROXY can stay false. If your proxy sends the original host only in X-Forwarded-Host, set NUXT_TRUST_PROXY=true and make sure the portal is reachable only through that proxy. Another domain needs one more server block (or a wildcard) pointing at the same portal.

Pages and routes#

URL What
/ Redirects to the default version.
/{version} Overview of a version: its services and their endpoints.
/{version}/{id} A text page or an endpoint. A readable title may follow the id.
/sitemap.xml, /robots.txt For search engines. The sitemap covers the default version.
/api/health Health check of the portal.

A hidden version opens through a preview link: https://docs.example.com/?preview=<token>. The portal keeps the token in a cookie for one hour and does not cache such answers. See Published Versions.

How the portal behaves#

  • The browser never calls SelfDocHub directly. The portal's own server routes do, so you do not need to configure CORS for the portal.
  • The design comes from the domain's style. See Styles, Branding and Design Tokens. The reader chooses the language and a light, dark or automatic theme; the choice is stored in a cookie.
  • The text of the documentation is drawn as components, never as raw HTML. Links are limited to http, https, mailto, relative and # addresses.
  • When SelfDocHub limits requests (429) or is unavailable, the page shows an error. An unknown domain, version or file is a 404.

Updating#

cd self-doc-hub-portal
git pull
docker compose up -d --build

The portal keeps no data, so there is nothing to back up.

Next steps#

Screenshots

Last updated: