docker-infrastructure/help-osk-docs/README.md

help-osk-docs — instructions site for client 05

Public static site at https://help.osk.team with user instructions, written in Markdown and built with Zensical (static-site generator from the Material for MkDocs team). Served by nginx behind the existing Traefik reverse proxy.

How it works

• docs/ — Markdown pages (+ docs/assets/ for images). This is the content.
• zensical.toml — site config (name, nav, theme, Markdown extensions).
• nginx.conf — static web-server config.
• docker-compose.yaml — two services:
  • help-osk-build — Zensical image, one-shot: runs zensical build --clean, rendering docs/ → site/, then exits. (The Zensical image is a builder, not a host server — by design.)
  • help-osk — nginx:alpine, serves site/, joins reverseproxy-nw. Starts only after the build succeeds.
• Traefik terminates TLS for help.osk.team (Let's Encrypt) and proxies to the help-osk container. Router/service live in ../traefik/dynamic/web.yml (help / help-osk).

Bind-mount / host-sync (important)

Content is bind-mounted, and Portainer GitOps can't bind-mount the repo checkout (relative paths resolve inside Portainer's container and become empty dirs). So the project must exist on the host at an absolute path — exactly like the Traefik config. This git repo is the source of truth.

Sync the project to the host (excluding the generated site/):

rsync -a --delete --exclude 'site/' \
  help-osk-docs/ <docker-host>:/mnt/containers/help-osk-docs/

The help-osk-build container creates /mnt/containers/help-osk-docs/site on the host during the build (Zensical's default output directory).

Deploy (Portainer)

1. DNS: help.osk.team → public edge IP, reachable on :80 (Let's Encrypt http-01). (Done.)
2. Sync this folder to /mnt/containers/help-osk-docs/ on the docker host (see above).
3. Make sure the Traefik help router/service in ../traefik/dynamic/web.yml is also synced to the host dynamic dir (/mnt/containers/traefik/container-data/dynamic/web.yml). Traefik's file provider (watch: true) picks it up live — no Traefik restart needed.
4. In Portainer, add a stack pointing at help-osk-docs/docker-compose.yaml (or redeploy the existing stack). The builder runs, then nginx comes up.

Add or edit an instruction

1. Add/edit a Markdown file in docs/ (e.g. docs/nastrojka-vpn.md).
2. Put images in docs/assets/, reference them: ![alt](assets/file.png) (size with ![alt](assets/file.png){ width="600" }).
3. Add the page to nav in zensical.toml.
4. Commit, re-sync to the host (step 2 above), redeploy the stack in Portainer (re-runs the build; nginx serves the updated site/).

Local preview (optional)

# Build and inspect output
docker run --rm -v "$PWD":/docs:Z zensical/zensical build --clean
# Live preview on http://localhost:8000
docker run --rm -p 8000:8000 -v "$PWD":/docs zensical/zensical