# Deploy the Public Site

The public site is a separate Nuxt 3 application with server-side rendering, [self-doc-hub-portal](https://github.com/SelfDocHub/self-doc-hub-portal). It reads the [public API](/documentation/public-site-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

```bash
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:

```bash
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:

```nginx
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](/documentation/public-site-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](/documentation/public-site-styles). 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

```bash
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

- [Publishing Domains](/documentation/public-site-domains)
- [Public API and Limits](/documentation/public-site-api)
- [Installation](/documentation/installation)

---
Source: https://selfdochub.com/documentation/public-site-portal
