Add help-osk-docs stack: Zensical instructions site for 05-osk
Static instructions site for client 05 served at help.osk.team. Markdown + images built by Zensical (zensical build) into public/, served by nginx behind Traefik. Content is bind-mounted from /mnt/containers/help-osk-docs (absolute host path — Portainer GitOps can't resolve relative mounts). Adds the help/help-osk router+service to traefik/dynamic/web.yml (TLS via Let's Encrypt, public/open). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
# 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/` → `public/`, then exits. (The Zensical image is a
|
||||
builder, **not** a host server — by design.)
|
||||
- `help-osk` — `nginx:alpine`, serves `public/`, 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 `public/`):
|
||||
|
||||
```sh
|
||||
rsync -a --delete --exclude 'public/' \
|
||||
help-osk-docs/ <docker-host>:/mnt/containers/help-osk-docs/
|
||||
```
|
||||
|
||||
The `help-osk-build` container creates `/mnt/containers/help-osk-docs/public`
|
||||
on the host during the build.
|
||||
|
||||
## 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: ``
|
||||
(size with `{ 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 `public/`).
|
||||
|
||||
## 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
|
||||
```
|
||||
Reference in New Issue
Block a user