Configure and test locally¶

Use these steps in the consumer repository. Requirements are Docker and Node.js; Harbor access is needed only when the registry does not allow the builder image to be pulled anonymously.

Configure the project¶

Create the ignored local configuration file:

npm run env:init

Edit .env for this project. Do not commit it. The required values are:

Variable	Value to set	Purpose
`DOCS_TOOLKIT_IMAGE`	`harbor.norrsign.se/norrsign/docs-toolkit:v1`	Released builder used for preview and static builds.
`DOCS_IMAGE`	For example, `harbor.norrsign.se/norrsign/my-project-docs`	This project's separate runtime image.
`SITE_NAME`	Public documentation title	Browser and site title.
`PROJECT_NAME`	Project name	Shared-theme project label.
`PROJECT_DESCRIPTION`	Public description	Site metadata and description.
`SITE_URL`	`https://docs-toolkit-consumer.norrsign.se` for this project	Canonical site URL.
`COPYRIGHT`	Optional	Footer text.
`PROJECT_LOGO`	`assets/project/docs-toolkit-consumer-logo.svg`	Logo path relative to `docs/`.
`PROJECT_FAVICON`	`assets/project/docs-toolkit-consumer-favicon.svg`	Favicon path relative to `docs/`.

v1 follows the latest compatible v1 builder release. Use an exact release, such as v1.0.3, only when this project must pin its builder version. Do not use a builder :latest tag: it is not published.

Build and preview with npm¶

Command	Use it when	Result
`npm run env:init`	Once per clone	Creates `.env` from `.env.example` when absent.
`npm run registry:login`	Harbor requires authentication	Prompts for Harbor credentials; never put them in `.env`.
`npm run image:pull`	Before the first build or after changing the builder tag	Pulls `DOCS_TOOLKIT_IMAGE`.
`npm start`	Previewing documentation	Serves the builder at http://localhost:8000.
`npm run build`	Inspecting generated static output	Strictly builds the site into ignored `site/`.
`npm run check`	Before a pull request or release	Runs the same strict static build as `build`.
`npm run image:runtime`	After a successful static build	Builds this project's local Nginx runtime image.
`npm run run:runtime`	Testing the runtime image	Serves the local runtime image at http://localhost:8080.

For a first local verification:

npm run registry:login   # Skip only when Harbor permits anonymous pulls.
npm run image:pull
npm start

Open http://localhost:8000. The preview stages a copy of docs/ when it starts, so stop and restart npm start after editing Markdown.

Before publishing, run the strict build and test the generated runtime image:

npm run check
npm run image:runtime
npm run run:runtime

Open http://localhost:8080. site/ is generated output and is excluded from Git. Build it again before rebuilding the runtime image after documentation changes.

Docker Compose is reserved for deploying the published production runtime. The repository intentionally has no local-development compose.yaml: its compose.production.yaml has one docs service that pulls the already-built runtime image. See Configure GitHub, publish, and deploy for that deployment.