Conventions

Internal domains

Domain	Service
`stepca.toolsera.lan`	Internal Step CA
`nexus.toolsera.lan`	Nexus — APT repo and artifact registry
`harbor.toolsera.lan`	Harbor — container registry and pull-through cache
`terrakube.toolsera.lan` / `terrakube-api.toolsera.lan`	Terrakube IaC UI

.toolsera.lan is internal-only and served with Step CA certificates. .toolsera.fr is the public zone, served with Let’s Encrypt through the Cloudflare tunnel.

Container images are pulled through Harbor rather than directly from upstream registries; image references look like harbor.toolsera.lan/ghcr_proxy_cache/<upstream>/<image>. The stack catalog strips that prefix so images read as their upstream names.

Formatting

Prettier formats everything, via npm at the repo root:

npx prettier --write .      # format
npx prettier --check .      # verify without writing

Markdown is wrapped at 90 columns — worth knowing when writing docs, because a code span can end up straddling a line break.

Pre-commit hooks

# One-time setup
./utils/utils-linux/install-pre-commit.sh
./utils/utils-linux/setup-pre-commit-repo.sh

# Run against everything
pre-commit run --all-files

The hooks cover:

gitleaks — secret scanning, configured in .gitleaks.toml, with known false-positives whitelisted in .gitleaksignore
Prettier — formatting
check-ansible-get-url-force.py — a repo-local hook in utils/pre-commit-hooks/

Naming

Compose stack directories match their host name, with two exceptions worth remembering:

Directory	Host
`remmina`	`remmina-kasm`
`tubearchivist`	`tube-archivist`

Package release tags are pkg/<package>-<version>. Container image release tags are image/<name>-<version>.

Editing these docs

Most pages on this site are not written here. They are the repo’s own README files, copied in at build time by docs/scripts/sync-content.mjs.

That means:

To change a synced page, edit its source file in the repo. Every synced page opens with a banner naming its source and linking to it on GitHub. Edits made to the copy under docs/src/content/docs/ are overwritten on the next build.
To change a hand-written page (this one, Architecture, the section index pages), edit it under docs/src/content/docs/ directly. Those are tracked in git; the synced pages are gitignored.
To add a repo README to the site, add an entry to the SOURCES array in docs/scripts/sync-content.mjs and, if it needs its own sidebar position, to the sidebar config in docs/astro.config.mjs.

The sync script also rewrites relative links: a link to another synced README becomes a link to its page here, and a link to any other repo file becomes a GitHub URL. Nothing 404s just because the file moved into the content collection.

The stack catalog is generated a step further — parsed directly out of the compose files by docs/scripts/generate-catalog.mjs, including include: directives. Adding a stack adds a catalog entry with no documentation change.

Local development

cd docs
npm install
npm run dev       # sync + dev server on localhost:4321
npm run build     # sync + production build into docs/dist/
npm test          # unit tests for the sync and catalog transforms
npm run clean     # remove generated pages

If a source file is renamed or deleted without updating SOURCES, the sync script prints the missing paths and exits non-zero, which fails the build rather than quietly dropping a page.