From ff9b26134990c4c87f2d62dae09964b6ac733d68 Mon Sep 17 00:00:00 2001 From: Nicole Rappe Date: Mon, 26 Jan 2026 19:12:20 -0700 Subject: [PATCH] Update Servers/Documentation/Zensical.md --- Servers/Documentation/Zensical.md | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/Servers/Documentation/Zensical.md b/Servers/Documentation/Zensical.md index ce63c93..f4ec167 100644 --- a/Servers/Documentation/Zensical.md +++ b/Servers/Documentation/Zensical.md @@ -4,6 +4,44 @@ After many years of Material for MKDocs being updated with new features and secu !!! info "Assumptions" It is assumed that you are deploying this server into `Ubuntu Server 24.04.2 LTS (Minimal)`. It is also assumed that you are running every command as a user with superuser privileges (e.g. `root`). +### Architectural Overview +It is useful to understand the flow of data and how everything inter-connects, so I have provided a sequence diagram that you can follow below: + +``` mermaid +sequenceDiagram + autonumber + actor Author as Docs Author + participant Gitea as Gitea Repo (git.bunny-lab.io) + participant Actions as Gitea Actions Workflow + participant Runner as Gitea Act Runner (zensical-docs-runner) + participant FS as Zensical Host FS (/srv/zensical/docs) + participant Watchdog as systemd: zensical-watchdog.service
(zensical serve) + participant Build as Zensical Builder + participant Site as Static Site Dir (/srv/zensical/site) + participant NGINX as NGINX (root=/srv/zensical/site) + participant Traefik as Traefik Reverse Proxy + participant User as Web Client + participant NTFY as NTFY (ntfy.bunny-lab.io) + + Author->>Gitea: Push changes to main + Gitea-->>Actions: Trigger workflow on push (main) + Actions-->>Runner: Schedule job (runs-on: zensical-host) + + Runner->>Gitea: Checkout repository (actions/checkout) + Runner->>FS: rsync repo → /srv/zensical/docs/
--delete, excludes, chmod D2775/F664 + + Note over FS,Watchdog: zensical serve watches docs directory for changes + Watchdog-->>Build: Detect filesystem changes (watchdog event) + Build->>Site: Rebuild static site output
(write into /srv/zensical/site) + + User->>Traefik: HTTPS request kb.bunny-lab.io + Traefik->>NGINX: Proxy to http://192.168.3.8:80 + NGINX->>Site: Read built files (index.html, assets) + NGINX-->>User: Serve newly-built content + + Runner-->>NTFY: Notify job status (always)
curl -d "…status…" topic=gitea-runners +``` + ### Setup Python Environment The first thing we need to do is install the necessary python packages and install the zensical software stack inside of it.