GitLab Pages custom domain (esysdox-ops.org)

This runbook documents how production documentation is published and how to avoid breaking the live site when using preview builds on develop.

Deployments

Branch	CI jobs	Public URL	Custom domain
master	docs:build → pages → docs:smoke (automatic)	esysdox-ops.org	Yes — production
develop	docs:build → pages (automatic)	esysdox-ops-d340b4.gitlab.io	No — preview only

Only the master deployment should own esysdox-ops.org. Preview publishes must not attach the production custom domain.

master serves production at esysdox-ops.org; develop keeps updating the .gitlab.io preview only and must not attach the production custom domain.

First-time custom domain setup

1. Open the GitLab project → Deploy → Pages.
2. Under Domains, add esysdox-ops.org (and optionally www).
3. Add the DNS records GitLab shows at your registrar:
   • A records to GitLab Pages IPs, or
   • CNAME to namespace.gitlab.io when using a subdomain pattern.
4. Complete TXT verification if GitLab prompts for domain ownership.
5. Wait for DNS propagation (minutes to hours).
6. Confirm HTTPS (Let's Encrypt) shows as active in GitLab — not HTTP only.
7. Set Pages access to Everyone if the documentation should be public (the project itself can remain private).

After a green master pipeline, docs:smoke curls key URLs on esysdox-ops.org (DOCS_SMOKE_BASE_URL in .gitlab-ci.yml) to catch broken deploys on the production custom domain.

DOCS_SITE_URL on master builds for https://esysdox-ops.org; preview on develop uses https://esysdox-ops-d340b4.gitlab.io.

Build-time URL settings

CI sets these for docs:build:

Branch	DOCS_SITE_URL	DOCS_SITE_BASE_URL
master	https://esysdox-ops.org	/
develop	https://esysdox-ops-d340b4.gitlab.io	/

scripts/assemble_docs.py passes them to Docusaurus and Sphinx <base href> patching. Do not use a subpath (/esysdox-ops/) with the current GitLab Pages hostname layout.

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 after green pages	DNS/HTTPS on esysdox-ops.org? Check GitLab Deploy → Pages domain status and job retries (index propagation).
Broken internal links in CI	docs:build runs Docusaurus with onBrokenLinks: throw — fix links before merge.

Local preview of a CI artifact

Download website/build/ from a docs:build job, then:

python scripts/serve_docs.py --root path/to/website/build --port 3000

Use the same DOCS_SITE_URL the job used when testing absolute links.

VPS alternative

To serve the same website/build/ artifact on your own nginx host instead of GitLab Pages, see Hosting documentation on a VPS.