Host the documentation site

This site is the apiome-suite-docs workspace of the private-suite repository, built with Docusaurus and published as a static site served by nginx at docs.suite.apiome.dev. It is a sibling of the open-source product's documentation at docs.apiome.dev and uses the same theme, so the two read as one product.

Build the image

From the private-suite root:

docker build -f apiome-suite-docs/Dockerfile -t apiome-suite-docs .
docker run --rm -p 3201:8080 apiome-suite-docs   # http://localhost:3201/

The build runs yarn docs:check — the page and link rules, then the production build, which fails on a broken link or anchor — so an image is never produced from a broken site. nginx serves it on port 8080 as a non-root user; GET /healthz answers ok.

The image is built for / on https://docs.suite.apiome.dev. Pass --build-arg DOCS_URL=… to set another public origin for canonical links and the sitemap, and --build-arg DOCS_BASE_URL=/path/ (leading and trailing slash) to serve it from a sub-path behind a proxy that strips the prefix.

The workflow

.github/workflows/suite-docs.yml runs the unit tests, the type-check and docs:check on every pull request that touches the site. On main it also builds the image, smoke-tests it (/healthz, the home page's title and the release-notes heading) and pushes it to the registry as apiome-suite-docs, tagged with the package version, latest and the commit SHA — the same pattern as the apiome-suite image. Set the SUITE_DOCS_URL repository variable to override the public origin baked into the build.

Run it locally

yarn install
yarn docs:dev      # http://localhost:3201/
yarn docs:check    # what CI runs