# 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](https://github.com/zensical/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/`):

```sh
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)

```sh
# 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
```