Working with Docker

Docker here builds and serves the documentation site — landing page, TypeDoc API reference, coverage report, and HonKit book. This is a library, so there is no application image: the deliverable is the tarball in lib/, not a container.

Layout

File Role
docker/docs.Dockerfile multi-stage: builds the project, then serves the result via nginx
docker/docker-compose.docs.yaml composes the image and publishes port 80
docker/nginx/index.html the landing page served at the site root
docker/nginx/default.conf nginx routing

Prerequisites

docker --version
docker compose --version

Build

npm run docker:build:docs
# docker compose -f docker/docker-compose.docs.yaml build --no-cache

Inside the container:

  1. npm ci
  2. npm run build:docs — TypeDoc
  3. npm run build:docs:coverage — the Jest suite, which also produces dist/coverage/
  4. npm run build:docs:book — HonKit

Only the three steps that produce something the site serves. Rollup is not among them: lib/ is the published package, and nothing in the image reads it.

The image is still gated on the tests, at step 3, and on the TypeDoc validation at step 2 — an undocumented export fails the image build. If either fails, the fix is in the code, not here.

Serve

npm run docker:serve:docs
# docker compose -f docker/docker-compose.docs.yaml up
Path Serves
http://localhost/ landing page
http://localhost/docs/ TypeDoc API reference
http://localhost/coverage/ Jest HTML coverage report
http://localhost/book/ HonKit developer book

The compose file publishes 80:80, so no port appears in the URL.

Routing

docker/nginx/default.conf serves everything from /usr/share/nginx/html and falls through $uri → $uri.html → $uri/ → 404, so HonKit's generated pages resolve without an explicit .html.

Customising the landing page

Edit docker/nginx/index.html — the logo character, heading, intro copy, and the three navigation cards are plain HTML and CSS with no build step. The <head> also carries the package's SEO metadata and JSON-LD. Rebuild after editing.

Without Docker

npm run build:static

Produces the same dist/ tree; serve it with any static file server.

Commands

npm run docker:build:docs
npm run docker:serve:docs

docker compose -f docker/docker-compose.docs.yaml up -d     # detached
docker compose -f docker/docker-compose.docs.yaml down      # stop
docker compose -f docker/docker-compose.docs.yaml build --no-cache

Troubleshooting

"Docker daemon not running"

Start Docker Desktop, or on Linux: systemctl start docker.

Port 80 already in use

Common — a local web server or another container usually has it. Change the host side of the mapping in docker/docker-compose.docs.yaml:

ports:
  - '8080:80'

and use http://localhost:8080/.

The build fails at the test step

That is the gate doing its job. Run npm test locally; the container adds nothing to the diagnosis.

results matching ""

    No results matching ""