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 a404.
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.