pipistrelloandClaude Opus 4.8
172de59391
zensical build outputs to site/ by default; nginx was mounting the empty public/ and returning 403 (directory index forbidden). Point the web-server mount, .gitignore and README at site/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
# 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: ``
|
|
(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 `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
|
|
```
|