GitLab Pages and custom domain
This portal publishes static documentation via GitLab Pages, following the same
pattern as esysdox-ops: preview on develop, production on master with a
custom domain.
Deployments
| Branch | CI jobs | Public URL | Custom domain |
|---|---|---|---|
develop | docs:build → pages | https://docs-portal-1c6c85.gitlab.io (preview) | No |
master | docs:build → pages → docs:smoke | https://esys-ai.org | Yes — production |
Only the master deployment should own esys-ai.org. The preview on develop
must not attach the production custom domain.
Production is served at https://esys-ai.org (custom domain verified in GitLab).
Preview stays on the project .gitlab.io hostname only — do not attach the custom
domain to develop.
Pipeline definition: .gitlab-ci.yml
Custom domain (esys-ai.org) — configured
Domain esys-ai.org is registered under Deploy → Pages → Domains with HTTPS active.
Pages access is public (Everyone). The repository can remain private.
Anonymous docs:smoke curls on master require this setting.
After DNS or domain changes, confirm verification and certificate status in GitLab Pages.
Preview URL on develop
Project Pages preview: https://docs-portal-1c6c85.gitlab.io
Configured in .gitlab-ci.yml as DOCS_PREVIEW_SITE_URL. DOCS_SITE_URL for Docusaurus
canonical links is set from this value on develop builds. If GitLab changes the
Pages hostname, update the variable and this document together.
Build-time URL settings
CI sets these for docs:build:
| Branch | DOCS_SITE_URL | DOCS_SITE_BASE_URL |
|---|---|---|
master | https://esys-ai.org | / |
develop | DOCS_PREVIEW_SITE_URL (see .gitlab-ci.yml) | / |
docusaurus.config.ts reads DOCS_SITE_URL and DOCS_SITE_BASE_URL from the
environment. Local npm start defaults to http://localhost:3000 when unset.
Do not use a subpath base URL (/docs-portal/) with the current Pages layout unless
GitLab project Pages is explicitly configured for subpath hosting.
Post-deploy smoke (docs:smoke)
On master, after pages publishes, docs:smoke curls key paths:
//common/intro//superbuild/intro/
Smoke uses DOCS_SMOKE_BASE_URL (https://esys-ai.org) on master so CI verifies
the production custom domain, not the .gitlab.io preview hostname.
Troubleshooting
| Symptom | Check |
|---|---|
| Domain shows old content | Latest master pipeline: pages + docs:smoke green? Hard-refresh browser. |
| HTTPS certificate pending | DNS correct? TXT verified? Wait for GitLab LE issuance. |
| Preview overwrote production | Custom domain attached to wrong environment — keep it on production only. |
docs:smoke fails with 403 | Set Pages access to Everyone, or confirm domain HTTPS is active. |
docs:smoke fails with connection error | DNS or certificate not propagated; check Deploy → Pages → Domains. |
| Broken internal links in CI | onBrokenLinks: throw in docusaurus.config.ts — fix links before merge. |
| Wrong canonical URLs on preview | Confirm DOCS_PREVIEW_SITE_URL matches Deploy → Pages preview URL. |
Local preview of a CI build
Download the build/ artifact from a docs:build job, then:
npm run serve
# or: npx serve build
Set DOCS_SITE_URL to the same value the CI job used when testing absolute links.